# Mensagens de áudio WhatsApp

Uma mensagem de áudio carrega uma URL pública que WhatsApp busca no momento do envio. Ela não tem legenda e pode, opcionalmente, ser renderizada como nota de voz.

## Enviar uma mensagem de áudio

Defina `audio.url`:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  audio: { url: "https://cdn.example.com/vm/9f2.ogg" },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/message-types/audio.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/message-types/audio.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/message-types/audio.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/message-types/audio.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/message-types/audio.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/message-types/audio.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/message-types/audio.curl.md)

A forma completa adiciona a flag opcional `voice`, o único outro campo que `audio` possui:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}
```

`audio` não tem o campo `caption`. `from` é obrigatório em toda mensagem de serviço: um número que seu espaço de trabalho possui, não um gerenciado por Bird.

## Limites

| Campo              | Limite                                                               | Aplicado por                                |
| ------------------ | -------------------------------------------------------------------- | ------------------------------------------- |
| Tamanho do arquivo | 16 MB                                                                | Apenas WhatsApp, no fetch (async)           |
| Formato            | AAC, AMR, MP3, M4A ou OGG com o codec OPUS, mono                     | Apenas WhatsApp, no fetch (async)           |
| `voice: true`      | requer `.ogg`/OPUS, mono; outros formatos fazem a transcrição falhar | Apenas WhatsApp, no fetch (async)           |
| `caption`          | não é um campo válido                                                | Bird, no accept (`422`, rejeição de schema) |
| `url`              | absoluta, `https`, tem host, sem espaço bruto                        | Bird, no accept (`422`)                     |

Bird verifica a forma da URL antes de qualquer coisa ser enfileirada; não verifica o tamanho real do arquivo, o formato ou o codec, e não verifica se um envio `voice: true` é de fato `.ogg`/OPUS. Apenas o próprio fetch de WhatsApp no momento do envio consegue fazer isso. Enviar um `caption` em uma mensagem de áudio não é um erro de tamanho; o campo não existe no schema desse braço, então falha como propriedade não reconhecida. Veja no hub [envio de mídia por URL](/docs/guides/whatsapp/message-types#sending-media-by-url) e [quando a mídia falha](/docs/guides/whatsapp/message-types#when-media-fails).

## Leitura de uma mensagem de áudio recebida

Uma mensagem de áudio recebida carrega o mesmo objeto `audio`, além de um `id` e `mime_type` que Bird aprendeu ao buscar o arquivo, e nenhum `caption` em nenhuma direção. Veja [Recebendo áudio WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/audio) para a leitura completa da entrada, o payload `whatsapp.received` e o que observar.

## Limites e modos de falha

- **A janela de atendimento ao cliente precisa estar aberta.** Áudio é uma mensagem de serviço, entregável apenas dentro de uma janela aberta; veja no hub a [janela de atendimento ao cliente](/docs/guides/whatsapp/message-types#the-customer-service-window).
- **Bird rejeita `http`; WhatsApp mesmo buscaria o conteúdo.** Veja no hub [envio de mídia por URL](/docs/guides/whatsapp/message-types#sending-media-by-url) para a verificação completa da forma.
- **Um fetch rejeitado ainda é cobrado.** Veja no hub [quando a mídia falha](/docs/guides/whatsapp/message-types#when-media-fails). O texto de rejeição específico de áudio de WhatsApp não foi medido de forma independente, então trate o mapeamento como inferido por simetria e não confirmado por causa.
- **A flag `voice` muda como o cliente do destinatário renderiza a mensagem, não o que Bird valida.** `voice: true` renderiza como nota de voz: faz download automático, exibe um ícone de microfone inline e pode ser transcrita. Para funcionar corretamente, é preciso um arquivo `.ogg` codificado com OPUS, mono; qualquer outro formato ainda é enviado, mas a transcrição falha no lado do destinatário. `voice` tem o padrão `false`.
- **O limiar do ícone de reprodução de WhatsApp e o sinal de "played" não são algo que Bird expõe.** WhatsApp documenta um comportamento do cliente em torno de notas de voz curtas e um estado de reproduzido, mas Bird não modela nenhum dos dois; não construa uma integração que espere ler qualquer um deles de volta a partir da API.
- **WhatsApp armazena em cache uma URL buscada por cerca de 10 minutos.** Reenviar a mesma URL dentro dessa janela serve o primeiro fetch novamente; varie a URL para forçar uma nova busca.

## Próximos passos

- [Mensagens de serviço WhatsApp](/docs/guides/whatsapp/message-types): a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
- [Vídeo](/docs/guides/whatsapp/message-types/video): para um clipe de vídeo em vez de áudio
- [Stickers](/docs/guides/whatsapp/message-types/stickers): outro braço de mídia sem campo de legenda
- [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp): o envelope da solicitação, o modelo `202` e retentativas seguras

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)