# 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

```json
{
  "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](/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.

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](/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` contém a estrutura `video` no envelope do evento:

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp): o envelope de entrada, busca de mídia e o webhook `whatsapp.received`
- [Mensagens de vídeo WhatsApp](/docs/guides/whatsapp/message-types/video): o lado de envio da mesma estrutura
- [Recebendo áudio](/docs/guides/whatsapp/receiving-whatsapp/audio): notas de voz e arquivos de áudio anexados
- [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)