# Ricevere video WhatsApp

Un filmato che un contatto registra o allega arriva come messaggio in entrata con `video`: lo stesso riferimento media usato da ogni ramo media in entrata, più l'eventuale didascalia digitata sotto.

## Cosa contiene un video in entrata

```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       | Cosa contiene                                                                     |
| ----------- | --------------------------------------------------------------------------------- |
| `id`        | Il file archiviato, da passare come `media_id` per recuperare i byte              |
| `url`       | Un URL Bird, da recuperare con la propria chiave API                              |
| `mime_type` | Il tipo di media che WhatsApp ha riportato per il filmato, ad esempio `video/mp4` |
| `caption`   | Il testo che il contatto ha digitato sotto il video; assente se non ne ha inviato |

Il ramo non contiene durata, dimensioni né miniatura. Ricavarli dal file stesso una volta ottenuti i byte, oppure dalla propria pipeline media.

`id` e `mime_type` compaiono solo su un video in entrata, perché Bird li ricava entrambi recuperando il file. Un video in uscita viene restituito con il `url` fornito e senza `id`.

## Recuperare i byte

Passare l'ID del messaggio e il `id` del media al metodo media del canale. La sezione [recupero dei media in entrata](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) dell'hub riporta quella chiamata in ogni linguaggio, insieme alle regole di redirect e header che segue.

Un video è l'oggetto più grande che un contatto può inviare, e il recupero serve i byte direttamente dallo storage anziché attraverso il API: fare streaming della risposta su disco o nel proprio bucket invece di bufferizzarla. Il messaggio e il suo media scadono insieme, 30 giorni dopo l'arrivo del messaggio; la sezione [recupero dei media in entrata](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) dell'hub definisce quella finestra e cosa restituiscono le letture una volta scaduta.

## Il payload del webhook

`whatsapp.received` contiene il ramo `video` nell'envelope dell'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
  }
}
```

Recuperare il filmato da un worker in coda anziché all'interno del gestore del webhook: l'endpoint deve rispondere rapidamente, e il media resta disponibile per l'intera finestra di conservazione.

## Aspetti da tenere d'occhio

- **Una nota video viene letta come un video.** La nota video circolare di WhatsApp arriva su questo ramo senza alcun flag che la distingua, a differenza dell'audio, dove una nota vocale imposta `voice`.
- **Un solo filmato per messaggio.** Più video arrivano come più messaggi in entrata, ciascuno con il proprio riferimento media.

## Passi successivi

- [Come funziona la ricezione](/docs/guides/whatsapp/receiving-whatsapp): l'envelope in entrata, il recupero dei media e il webhook `whatsapp.received`
- [Messaggi video WhatsApp](/docs/guides/whatsapp/message-types/video): il lato invio dello stesso ramo
- [Ricevere audio](/docs/guides/whatsapp/receiving-whatsapp/audio): note vocali e file audio allegati
- [Eventi WhatsApp](/docs/guides/whatsapp/events): l'elenco completo degli eventi, tramite API o webhook

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