# Recebendo áudio WhatsApp

O áudio que um contato envia chega como uma mensagem recebida contendo `audio`. Esse braço cobre tanto uma nota de voz gravada no chat quanto um arquivo de áudio anexado, e `voice` é o que diferencia os dois.

## O que um áudio recebido contém

```json
{
  "id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "audio": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "audio/ogg; codecs=opus",
    "voice": true
  },
  "created_at": "2026-08-25T09:07:32Z"
}
```

| Campo       | O que contém                                                                              |
| ----------- | ----------------------------------------------------------------------------------------- |
| `id`        | O arquivo armazenado, para passar como `media_id` ao obter os bytes                       |
| `url`       | Uma URL Bird, obtida com sua chave API                                                    |
| `mime_type` | O tipo de mídia que WhatsApp reportou, como `audio/ogg; codecs=opus` para uma nota de voz |
| `voice`     | `true` para uma nota de voz gravada no chat, em vez de um arquivo de áudio anexado        |

`caption` não existe nesse braço em nenhuma direção, então uma mensagem de áudio nunca carrega texto junto. Um contato que queira adicionar palavras envia uma [mensagem de texto](/docs/guides/whatsapp/receiving-whatsapp/plain-text) separada.

Uma nota de voz é baixada automaticamente no cliente WhatsApp e pode ser transcrita ali para o destinatário. Bird repassa o áudio e não o transcreve, então a transcrição que o seu contato vê no próprio app não faz parte da mensagem que você lê.

## Obtendo os bytes

Passe o ID da mensagem e o `id` de mídia para o método de mídia do canal. A página [obtendo mídia recebida](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) do hub traz essa chamada em todas as linguagens, junto com as regras de redirecionamento e cabeçalho que ela segue.

`mime_type` indica o contêiner e o codec, e uma nota de voz é Opus em um contêiner Ogg, e não MP3 ou AAC, que é o mais provável para um anexo. Leia o tipo a partir do campo, e não da extensão do arquivo em `url`, que não contém nenhuma, e verifique-o antes de enviar os bytes a um serviço de transcrição que aceita apenas alguns formatos. A mensagem e sua mídia expiram juntas, 30 dias após a chegada da mensagem; a página [obtendo mídia recebida](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) do hub define essa janela e o que as leituras retornam depois que ela passa.

## O payload do webhook

`whatsapp.received` carrega o braço `audio` no envelope do evento, incluindo o flag `voice`:

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:07:32.451Z",
  "data": {
    "whatsapp_id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "audio": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "audio/ogg; codecs=opus",
      "voice": true
    },
    "tags": null,
    "metadata": null
  }
}
```

Um fluxo automatizado que responde a notas de voz lê `voice` aqui, antes de obter qualquer coisa: uma fila de suporte que transcreve gravações mas encaminha arquivos de música anexados pode se basear apenas no flag.

## Pontos de atenção

- **Leia `voice` como um flag que marca uma nota de voz.** Qualquer outra coisa, incluindo a ausência do campo, é um anexo de áudio comum.
- **Nenhuma duração é reportada.** O braço não carrega o comprimento, então leia-o do arquivo após obtê-lo, se uma fila precisar.

## Próximos passos

- [Como o recebimento funciona](/docs/guides/whatsapp/receiving-whatsapp): o envelope de entrada, obtenção de mídia e o webhook `whatsapp.received`
- [Mensagens de áudio WhatsApp](/docs/guides/whatsapp/message-types/audio): o lado de envio do mesmo braço
- [Recebendo vídeo](/docs/guides/whatsapp/receiving-whatsapp/video): clipes, com uma legenda que o braço de áudio não comporta
- [Eventos WhatsApp](/docs/guides/whatsapp/events): a lista completa de eventos, via API ou webhooks

## 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)