WhatsApp-Video empfangen

Ein Clip, den ein Kontakt aufnimmt oder anhängt, kommt als eingehende Nachricht mit video an: dieselbe Medienreferenz, die jeder eingehende Medien-Arm verwendet, plus eine etwaige Bildunterschrift, die der Kontakt darunter eingegeben hat.

Was ein eingehendes Video enthält

Codebeispiel

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

Feld	Was es enthält
id	Die gespeicherte Datei, die Sie beim Abrufen der Bytes als media_id übergeben
url	Eine Bird-URL, die Sie mit Ihrem API-Schlüssel abrufen
mime_type	Der Medientyp, den WhatsApp für den Clip gemeldet hat, z. B. video/mp4
caption	Der Text, den der Kontakt unter dem Video eingegeben hat; fehlt, wenn keiner gesendet wurde

Der Arm enthält keine Dauer, keine Abmessungen und kein Thumbnail. Lesen Sie diese Werte aus der Datei selbst aus, sobald Sie die Bytes haben, oder aus Ihrer eigenen Medien-Pipeline.

id und mime_type erscheinen nur bei einem eingehenden Video, da Bird beides durch Abrufen der Datei ermittelt. Ein ausgehendes Video wird mit dem von Ihnen übergebenen url und ohne id zurückgelesen.

Bytes abrufen

Übergeben Sie die Nachrichten-ID und die Medien-id an die Medienmethode des Kanals. Die Seite Eingehende Medien abrufen des Hubs enthält diesen Aufruf in jeder Sprache sowie die Redirect- und Header-Regeln, denen er folgt.

Ein Video ist das Größte, was ein Kontakt Ihnen voraussichtlich senden wird, und der Abruf liefert die Bytes direkt aus dem Speicher statt über die API. Streamen Sie die Antwort daher auf die Festplatte oder in Ihren eigenen Bucket, statt sie zu puffern. Die Nachricht und ihre Medien laufen gemeinsam ab, 30 Tage nach Eingang der Nachricht; die Seite Eingehende Medien abrufen des Hubs beschreibt dieses Zeitfenster und was die Lesezugriffe zurückgeben, wenn es abgelaufen ist.

Der Webhook-Payload

whatsapp.received enthält den video-Arm im Event-Envelope:

Codebeispiel

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

Rufen Sie den Clip aus einem Queued Worker ab, nicht innerhalb des Webhook-Handlers: Der Endpunkt muss schnell antworten, und die Medien bleiben über das gesamte Aufbewahrungsfenster verfügbar.

Worauf Sie achten sollten

Eine Videonachricht wird als Video gelesen. Die runde Videonachricht von WhatsApp kommt auf diesem Arm ohne unterscheidendes Flag an, anders als bei Audio, wo eine Sprachnachricht voice setzt.
Ein Clip pro Nachricht. Mehrere Videos kommen als mehrere eingehende Nachrichten an, jede mit eigener Medienreferenz.

Nächste Schritte

So funktioniert der Empfang: der eingehende Envelope, Medienabruf und der whatsapp.received-Webhook
WhatsApp-Videonachrichten: die Sendeseite desselben Arms
Audio empfangen: Sprachnachrichten und angehängte Audiodateien
WhatsApp-Events: die vollständige Event-Liste, über die API oder Webhooks