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

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

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 te weten komt door het bestand op te halen. Als je een uitgaande video terugleest, bevat die de url die je hebt opgegeven en geen id.

De bytes ophalen

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

Een video is waarschijnlijk het grootste bestand dat een contact je stuurt. Het ophalen levert de bytes rechtstreeks uit de opslag in plaats van via de API, dus stream het antwoord naar schijf of naar je eigen bucket in plaats van het te bufferen. Het bericht en de bijbehorende media verlopen samen, 30 dagen nadat het bericht binnenkomt. De hubpagina inkomende media ophalen beschrijft die termijn en wat het uitlezen oplevert zodra die verstreken is.

De webhook-payload

whatsapp.received bevat de video-arm in de event-envelope:

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

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-webhooks: elk event waarop je je kunt abonneren