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

Exemplo de código

{
  "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 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 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 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:

Exemplo de código

{
  "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: o envelope de entrada, obtenção de mídia e o webhook whatsapp.received
Mensagens de áudio WhatsApp: o lado de envio do mesmo braço
Recebendo vídeo: clipes, com uma legenda que o braço de áudio não comporta
Eventos WhatsApp: a lista completa de eventos, via API ou webhooks

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação