WhatsApp-video ontvangen

Een clip die een contact opneemt of bijvoegt komt binnen als een inkomend bericht met video: dezelfde mediareferentie die elke inkomende media-arm gebruikt, plus een eventueel bijschrift dat ze eronder hebben getypt.

Wat een inkomende video bevat

Codevoorbeeld

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

Veld	Wat het bevat
id	Het opgeslagen bestand, om als media_id mee te geven bij het ophalen van de bytes
url	Een Bird-URL, op te halen met je API-sleutel
mime_type	Het mediatype dat WhatsApp voor de clip heeft gemeld, zoals video/mp4
caption	De tekst die het contact onder de video heeft getypt; afwezig als ze niets hebben gestuurd

De arm bevat geen duur, geen afmetingen en geen thumbnail. Lees die uit het bestand zelf zodra je de bytes hebt, of uit je eigen mediapipeline.

id en mime_type verschijnen alleen bij een inkomende video, omdat Bird beide leert door het bestand op te halen. Een uitgaande video komt terug met de url die je hebt opgegeven en zonder id.

De bytes ophalen

Geef het bericht-ID en de media-id door aan de mediamethode van het kanaal. De hub's inkomende media ophalen bevat die aanroep in elke taal, samen met de redirect- en headerregels die hij volgt.

Een video is het grootste dat een contact je waarschijnlijk stuurt, en de fetch serveert de bytes rechtstreeks vanuit opslag in plaats van via de API. Stream het antwoord daarom naar schijf of naar je eigen bucket in plaats van het te bufferen. Het bericht en zijn media verlopen samen, 30 dagen na aankomst van het bericht; de hub's inkomende media ophalen beheert dat venster en wat de reads teruggeven zodra het verstreken is.

De webhook-payload

whatsapp.received draagt de video-arm op de event-envelope:

Codevoorbeeld

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

Haal de clip op vanuit een worker in een wachtrij in plaats van in de webhook-handler: het endpoint moet snel antwoorden, en de media blijft beschikbaar gedurende het hele retentievenster.

Aandachtspunten

Een videonotitie wordt gelezen als een video. De ronde videonotitie van WhatsApp komt op deze arm binnen zonder een vlag die hem onderscheidt, anders dan bij audio, waar een spraaknotitie voice zet.
Eén clip per bericht. Meerdere video's komen binnen als meerdere inkomende berichten, elk met een eigen mediareferentie.

Volgende stappen

Hoe ontvangen werkt: de inkomende envelope, media ophalen en de whatsapp.received-webhook
WhatsApp-videoberichten: de verzendzijde van dezelfde arm
Audio ontvangen: spraaknotities en bijgevoegde audiobestanden
WhatsApp-events: de volledige eventlijst, via de API of webhooks

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channel Begrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builder Ontdek de mogelijkheidWhatsApp

Probeer de oefening en ontvang een implementatieoverzicht