Sign inGet started

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:
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);
A forma completa adiciona a flag opcional voice, o único outro campo que audio possui:
Exemplo de código
{
  "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

CampoLimiteAplicado por
Tamanho do arquivo16 MBApenas WhatsApp, no fetch (async)
FormatoAAC, AMR, MP3, M4A ou OGG com o codec OPUS, monoApenas WhatsApp, no fetch (async)
voice: truerequer .ogg/OPUS, mono; outros formatos fazem a transcrição falharApenas WhatsApp, no fetch (async)
captionnão é um campo válidoBird, no accept (422, rejeição de schema)
urlabsoluta, https, tem host, sem espaço brutoBird, 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 e quando a mídia falha.

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 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.
  • Bird rejeita http; WhatsApp mesmo buscaria o conteúdo. Veja no hub envio de mídia por URL para a verificação completa da forma.
  • Um fetch rejeitado ainda é cobrado. Veja no hub quando a mídia falha. 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