Recebendo vídeo WhatsApp

Um clipe que um contato grava ou anexa chega como uma mensagem recebida contendo video: a mesma referência de mídia que toda estrutura de mídia recebida usa, além de qualquer legenda que ele digitou abaixo.

O que um vídeo recebido contém

Exemplo de código

{
  "id": "wam_01kyc5r9pewu7s3j6m0xyd5qgb",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "video": {
    "id": "waf_01kyc4n5yr8xit1e9o4qsw7ufa",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyc5r9pewu7s3j6m0xyd5qgb/media/waf_01kyc4n5yr8xit1e9o4qsw7ufa",
    "mime_type": "video/mp4",
    "caption": "The rattle starts around 0:12"
  },
  "created_at": "2026-08-25T09:11:48Z"
}

Campo	O que contém
id	O arquivo armazenado, para passar como media_id ao baixar os bytes
url	Uma URL Bird, acessada com sua chave API
mime_type	O tipo de mídia que WhatsApp informou para o clipe, como video/mp4
caption	O texto que o contato digitou abaixo do vídeo; ausente quando não enviou nenhum

A estrutura não traz duração, dimensões nem miniatura. Leia esses dados do próprio arquivo depois de ter os bytes, ou do seu pipeline de mídia.

id e mime_type aparecem apenas em um vídeo recebido, já que Bird obtém ambos ao baixar o arquivo. Um vídeo enviado retorna com o url que você forneceu e sem id.

Baixando os bytes

Passe o ID da mensagem e o id da mídia para o método de mídia do canal. A página baixando mídia recebida do hub traz essa chamada em todas as linguagens, junto com as regras de redirecionamento e cabeçalho que ela segue.

Um vídeo é o maior conteúdo que um contato provavelmente vai enviar para você, e a busca serve os bytes diretamente do armazenamento em vez de passar pelo API. Por isso, faça streaming da resposta para disco ou para seu próprio bucket em vez de armazená-la em buffer. A mensagem e sua mídia expiram juntas, 30 dias após a chegada da mensagem; a página baixando mídia recebida do hub define essa janela e o que as leituras retornam depois que ela passa.

O payload do webhook

whatsapp.received contém a estrutura video no envelope do evento:

Exemplo de código

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:11:48.204Z",
  "data": {
    "whatsapp_id": "wam_01kyc5r9pewu7s3j6m0xyd5qgb",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "video": {
      "id": "waf_01kyc4n5yr8xit1e9o4qsw7ufa",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyc5r9pewu7s3j6m0xyd5qgb/media/waf_01kyc4n5yr8xit1e9o4qsw7ufa",
      "mime_type": "video/mp4",
      "caption": "The rattle starts around 0:12"
    },
    "tags": null,
    "metadata": null
  }
}

Baixe o clipe a partir de um worker em fila em vez de dentro do handler do webhook: o endpoint precisa responder rapidamente, e a mídia permanece disponível durante toda a janela de retenção.

Pontos de atenção

Uma nota de vídeo é lida como vídeo. A nota de vídeo circular do WhatsApp chega nessa estrutura sem nenhum flag que a diferencie, diferente do áudio, em que uma nota de voz define voice.
Um clipe por mensagem. Vários vídeos chegam como várias mensagens recebidas, cada uma com sua própria referência de mídia.

Próximos passos

Como funciona o recebimento: o envelope de entrada, busca de mídia e o webhook whatsapp.received
Mensagens de vídeo WhatsApp: o lado de envio da mesma estrutura
Recebendo áudio: notas de voz e arquivos de áudio anexados
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