WhatsApp-Bilder empfangen

Ein Foto oder eine Grafik, die ein Kontakt sendet, kommt als eingehende Nachricht mit image an: eine Referenz auf die Datei, die Bird für Sie gespeichert hat, sowie die Bildunterschrift, die der Kontakt darunter eingegeben hat.

Was ein eingehendes Bild enthält

Codebeispiel

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

Feld	Was es enthält
id	Die gespeicherte Datei, die Sie als media_id beim Abrufen der Bytes übergeben
url	Eine Bird-URL, die Sie mit Ihrem API-Key abrufen
mime_type	Der Medientyp, den WhatsApp für die Datei gemeldet hat, z. B. image/jpeg
caption	Der Text, den der Kontakt unter das Bild geschrieben hat; fehlt, wenn keiner gesendet wurde

id und mime_type erscheinen nur bei einem eingehenden Bild: Bird ermittelt beides durch Abrufen der Datei und hat das von Ihnen gesendete nie gespeichert. Ein ausgehendes Bild wird mit der von Ihnen übergebenen url zurückgelesen, ohne id.

Behandeln Sie mime_type als Angabe von WhatsApp und nicht als Garantie und verzweigen Sie danach statt nach der Dateierweiterung in url, die keine enthält.

Die Bytes abrufen

url und id zeigen beide auf dieselbe gespeicherte Datei: Übergeben Sie die Nachrichten-ID und die Medien-id an die Media-Methode des Channels – in jedem SDK, der CLI oder cURL. Die Seite Eingehende Medien abrufen im Hub enthält diesen Aufruf in jeder Sprache sowie die Redirect- und Header-Regeln, denen er folgt.

Die Nachricht und ihre Medien verfallen gemeinsam, 30 Tage nach Eingang der Nachricht. Die Seite Eingehende Medien abrufen im Hub beschreibt dieses Zeitfenster und was die Lesezugriffe zurückgeben, sobald es abgelaufen ist. Speichern Sie jedes Bild, das Sie länger benötigen, solange die Nachricht noch lesbar ist.

Der Webhook-Payload

whatsapp.received liefert den image-Zweig auf dem Event-Envelope, einschließlich Medienreferenz:

Codebeispiel

{
  "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?"
    },
    "tags": null,
    "metadata": null
  }
}

Der Webhook feuert, wenn die Nachricht eintrifft – das ist auch der Beginn des Aufbewahrungsfensters. Ein Endpunkt, der den Abruf in eine Queue stellt, statt ihn inline durchzuführen, hat das gesamte Fenster zum Nachholen.

Worauf Sie achten sollten

Die Bildunterschrift gehört dem Kontakt. Sie kommt als reiner Text ohne Formatierung oder Entity-Informationen an; rendern Sie sie als Text.
Ein Bild pro Nachricht. Wenn ein Kontakt mehrere Fotos sendet, entstehen mehrere eingehende Nachrichten, jede mit eigenem id und eigener Medienreferenz. Gruppieren Sie sie nach from und Eingangszeit; kein Array fasst sie zusammen.

Nächste Schritte

So funktioniert der Empfang: der eingehende Envelope, das Abrufen von Medien und der whatsapp.received-Webhook
WhatsApp-Bildnachrichten: die Sendeseite desselben Zweigs
Dokumente empfangen: dieselbe Medienstruktur, mit dem Dateinamen des Absenders
WhatsApp-Events: die vollständige Event-Liste, über die API oder Webhooks