Dokumentation
Sign inGet started
Jetzt starten
Anleitungen
API-Referenz
SDKs
CLI
Wissensdatenbank
Changelog

WhatsApp-Nachrichten empfangen

Eingehende Nachrichten landen auf derselben Ressource wie ausgehende – es gibt keinen separaten Inbox-Endpunkt zum Abfragen. Lesen Sie sie über die Nachrichtenliste im Dashboard oder über die API mit GET /v1/whatsapp/messages/{id}, nachdem Sie die Liste auf eingehende Nachrichten gefiltert haben.
Jede eingehende Nachricht verlängert das Kundenservice-Fenster auf 24 Stunden nach dem Zeitstempel dieser Nachricht. Dadurch wird eine freie Antwort Ihrerseits zustellbar. Eine Nachricht, die Bird verspätet erreicht, trägt daher das Fenster, das der Kontakt tatsächlich gewährt hat, und eine bereits gespeicherte spätere Frist wird nie verkürzt.

Was eine eingehende Nachricht enthält

Jede eingehende Nachricht hat denselben Umschlag: eine id, direction: "inbound", den Kontakt in from, Ihre eigene Nummer in to, einen status von received und einen created_at. Genau ein Inhaltsfeld steht daneben und benennt, was der Kontakt gesendet hat:
Codebeispiel
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "text": { "body": "Is my order out for delivery yet?" },
  "created_at": "2026-08-25T09:04:11Z"
}
from benennt den Kontakt anhand der Identität, die WhatsApp meldet: eine E.164-phone_number, eine bsuid oder beides, plus username und display_name, die sie veröffentlichen. Ein Kontakt, der einen WhatsApp-Benutzernamen angenommen hat, kann Sie ganz ohne Telefonnummer erreichen; siehe geschäftsbezogene Benutzer-IDs für das, was Sie speichern und wie Sie nach einer Nummer fragen.
Eines dieser Inhaltsfelder, ein Arm, enthält das Gesendete, und genau ein Arm ist bei jeder Nachricht gesetzt. Jeder hat eine eigene Seite mit der Leseform, dem whatsapp.received-Payload und worauf Sie achten sollten:
FeldWas eine eingehende Nachricht enthält
textbody, die Nachricht, die der Kontakt getippt hat
imageEine id, url, mime_type und eventuelle caption
videoDieselben Medienfelder, plus eventuelle caption
audioDieselben Medienfelder, plus voice bei einer Sprachnachricht; es gibt keine Bildunterschrift
stickerDieselben Medienfelder, plus animated
documentDieselben Medienfelder, plus eventuelle filename und caption
locationlatitude und longitude, und manchmal name, address oder ein url
contact_cardsEine oder mehrere Kontaktkarten, die der Kontakt geteilt hat
interactive_replyslug und text des Buttons oder der Zeile, die der Kontakt angetippt hat
unsupportedDer WhatsApp-Inhaltstyp, den die API nicht modelliert, z. B. eine Bestellung
Zwei Taps landen auf einem Arm, den Sie vielleicht nicht erwarten. Eine Standortanfrage wird als gewöhnliche eingehende location beantwortet, und eine Kontaktinfo-Anfrage als contact_cards – eine Integration, die nur interactive_reply auf einen Tap überwacht, verpasst also beide.

Eingehende Medien abrufen

Ein eingehendes image, video, audio, sticker oder document kommt als Verweis auf eine Datei an, die Bird gespeichert hat, nicht als die Datei selbst:
Codebeispiel
{
  "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?"
  }
}
Rufen Sie die Bytes mit der Media-Methode des Channels ab und übergeben Sie die Nachrichten-ID und die Medien-id:
const media = await bird.whatsapp.messages.media(
  "wam_01kya19eknftrs2s6p82asmvnh",
  "waf_01kyb2m4xq7whs0d8n3prv6tez",
);
console.log(media.contentType, media.contentLength);
Sie erhalten die Bytes mit dem für sie deklarierten mime_type-Speicher zurück. Eine ID, die Bird nicht erkennt, gibt 404 zurück, und eine ausgehende Nachricht hat keine gespeicherten Medien zum Ausliefern.
Eine Nachricht ist 30 Tage nach dem Eingang lesbar, und ihre Medien überdauern sie nie. Dieser Endpunkt liest die Nachricht, bevor er die Datei ausliefert – sobald dieses Fenster abgelaufen ist, antworten beide mit 404. Speichern Sie jede Datei, die Sie länger brauchen, solange die Nachricht noch lesbar ist. Der einzige Fall, der früher endet, ist, wenn die gespeicherten Bytes vor Ablauf des Fensters verschwinden: Der Abruf antwortet mit 410 E15021, und die Nachricht ist weiterhin mit mime_type und caption der Medien lesbar.
Intern antwortet dieser Endpunkt mit 302 und einer vorsignierten URL, die 15 Minuten gültig ist. Die SDKs und die CLI übernehmen diesen Zwischenschritt für Sie. Beim direkten Aufruf bringt die vorsignierte URL ihre eigene Berechtigung mit, sodass die weitergeleitete Anfrage nicht zusätzlich Ihren Authorization-Header senden darf. Beides zusammen schlägt fehl. curl -L entfernt den Header bei einem Cross-Host-Redirect automatisch; ein Client, der Header unverändert weiterleitet, muss die Location als separate, nicht authentifizierte Anfrage abrufen.

Zitierte Antworten

in_reply_to_message_id benennt die Nachricht, auf die eine eingehende antwortet, wenn WhatsApp sie als Antwort markiert:
Codebeispiel
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that one" }
}
WhatsApp markiert nicht jede Antwort, und eine nicht markierte enthält überhaupt keine ID. Das Feld wird auch weggelassen, wenn die zitierte Nachricht keiner zugeordnet werden kann, die Bird gespeichert hat: eine Nachricht, die vor Beginn der Aufzeichnung in diesem Workspace gesendet wurde, oder eine, die die 15 Tage überschreitet, die Bird die eigenen Nachrichten-IDs von WhatsApp aufbewahrt. Ein Fehlschlag lässt das Feld weg, statt eines zu melden – das sieht genauso aus wie eine Antwort, die auf nichts antwortet.
Behandeln Sie das Feld als Hinweis, nicht als Schlüssel. metadata bei Ihrem eigenen Versand hilft hier nicht, weil es auf Ihrer Nachricht bleibt und nie zur Antwort des Kontakts wandert. Eine Integration, die wissen muss, zu welcher Frage eine Antwort gehört, verfolgt die letzte an den Kontakt gestellte Frage selbst. Siehe Eine Nachricht zitieren für die ausgehende Seite.

Der Webhook

Abonnieren Sie whatsapp.received, um auf eine eingehende Nachricht bei Eintreffen zu reagieren, statt die Liste abzufragen. Der Payload enthält den Inhalt zusätzlich zum Event-Umschlag, sodass ein Endpunkt keinen Folgeabruf benötigt:
Codebeispiel
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "interactive_reply": {
      "type": "button",
      "button": { "slug": "cancel-booking", "text": "Cancel" }
    },
    "tags": null,
    "metadata": null
  }
}
Siehe WhatsApp-Events für den vollständigen Umschlag und die restliche Event-Liste.

Nächste Schritte

Verwandte Ressourcen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.

Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten