WhatsApp-afbeeldingen ontvangen

Een foto of afbeelding die een contact stuurt, komt binnen als een inkomend bericht met image: een verwijzing naar het bestand dat Bird voor je heeft opgeslagen, plus het bijschrift dat ze eronder hebben getypt.

Wat een inkomende afbeelding bevat

{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "image": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "image/jpeg",
    "caption": "Is this the right part?"
  },
  "created_at": "2026-08-25T09:04:11Z"
}

id en mime_type verschijnen alleen bij een inkomende afbeelding: Bird achterhaalt beide door het bestand op te halen, en heeft het bestand dat je hebt verstuurd nooit opgeslagen. Een uitgaande afbeelding wordt teruggelezen met de url die je hebt opgegeven en zonder id.

Behandel mime_type als het rapport van WhatsApp en niet als een garantie, en vertak op deze waarde in plaats van op de bestandsextensie in url, want die bevat er geen.

De bytes ophalen

url en id verwijzen beide naar hetzelfde opgeslagen bestand: geef het bericht-ID en de media-id door aan de mediamethode van het kanaal, in elke SDK, de CLI of cURL. De pagina inkomende media ophalen in de hub bevat die aanroep in elke taal, samen met de redirect- en headerregels die de aanroep volgt.

Het bericht en de media verlopen samen, 30 dagen na aankomst van het bericht. De pagina inkomende media ophalen in de hub beschrijft die termijn en wat leesverzoeken teruggeven nadat die is verstreken. Sla elke afbeelding die je langer nodig hebt op zolang het bericht nog leesbaar is.

De webhook-payload

whatsapp.received bevat de image-arm op de event-envelope, inclusief mediareferentie:

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "image": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "image/jpeg",
      "caption": "Is this the right part?"
    }
  }
}

De webhook wordt afgevuurd wanneer het bericht binnenkomt, en dat is ook het moment waarop het bewaarvenster start. Een endpoint dat het ophalen in een wachtrij plaatst in plaats van het direct te doen, heeft dus het volledige venster om de achterstand in te halen.

Aandachtspunten

• Het bijschrift is van het contact. Het komt binnen als platte tekst zonder opmaak of entity-informatie, dus render het als tekst.
• Eén afbeelding per bericht. Wanneer een contact meerdere foto's stuurt, ontstaan er meerdere inkomende berichten, elk met een eigen id en een eigen mediareferentie. Groepeer ze op from en aankomsttijd; er is geen array die ze bundelt.

Volgende stappen

• Hoe ontvangen werkt: de inkomende envelope, media ophalen en de whatsapp.received-webhook
• WhatsApp-afbeeldingsberichten: de verzendzijde van dezelfde arm
• Documenten ontvangen: dezelfde mediavorm, met de bestandsnaam van de afzender
• WhatsApp-webhooks: elk event waarop je je kunt abonneren