Recevoir une vidéo WhatsApp

Un clip qu'un contact enregistre ou joint arrive sous forme de message entrant portant video : la même référence média utilisée par chaque branche de média entrant, plus la légende éventuellement saisie en dessous.

Ce que porte une vidéo entrante

Exemple de code

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

Champ	Ce qu'il porte
id	Le fichier stocké, à transmettre comme media_id lors de la récupération des octets
url	Une URL Bird, récupérée avec votre clé API
mime_type	Le type de média que WhatsApp a signalé pour le clip, par exemple video/mp4
caption	Le texte que le contact a saisi sous la vidéo ; absent s'il n'en a envoyé aucun

La branche ne porte ni durée, ni dimensions, ni miniature. Lisez ces informations depuis le fichier lui-même une fois les octets récupérés, ou depuis votre propre pipeline média.

id et mime_type n'apparaissent que sur une vidéo entrante, car Bird les obtient tous deux en récupérant le fichier. Une vidéo sortante est relue avec le url que vous avez fourni et sans id.

Récupérer les octets

Transmettez l'identifiant du message et le id du média à la méthode média du canal. La page récupérer un média entrant du hub présente cet appel dans chaque langage, ainsi que les règles de redirection et d'en-têtes qu'il suit.

Une vidéo est le contenu le plus volumineux qu'un contact est susceptible de vous envoyer, et la récupération sert les octets directement depuis le stockage plutôt que via le API. Diffusez donc la réponse vers le disque ou vers votre propre bucket au lieu de la mettre en mémoire tampon. Le message et son média expirent ensemble, 30 jours après l'arrivée du message ; la page récupérer un média entrant du hub détient cette fenêtre et ce que les lectures renvoient une fois celle-ci écoulée.

Le payload du webhook

whatsapp.received porte la branche video sur l'enveloppe d'événement :

Exemple de code

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

Récupérez le clip depuis un worker en file d'attente plutôt que dans le gestionnaire de webhook : le point de terminaison doit répondre rapidement, et le média reste disponible pendant toute la fenêtre de rétention.

Points de vigilance

Une note vidéo est lue comme une vidéo. La note vidéo ronde de WhatsApp arrive sur cette branche sans indicateur permettant de la distinguer, contrairement à l'audio, où une note vocale définit voice.
Un seul clip par message. Plusieurs vidéos arrivent sous forme de plusieurs messages entrants, chacun avec sa propre référence média.

Étapes suivantes

Fonctionnement de la réception : l'enveloppe entrante, la récupération de média et le webhook whatsapp.received
Messages vidéo WhatsApp : le côté envoi de la même branche
Recevoir de l'audio : notes vocales et fichiers audio joints
Événements WhatsApp : la liste complète des événements, via le API ou les webhooks

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

Essayez la pratique et obtenez un guide d'implémentation