WhatsApp-Dokumente empfangen

Ein PDF, eine Tabelle oder jede andere Datei, die ein Kontakt anhängt, kommt als eingehende Nachricht mit document an: die gemeinsame Medienreferenz plus der Name, den das Gerät des Kontakts der Datei gegeben hat.

Was ein eingehendes Dokument enthält

Codebeispiel

{
  "id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "document": {
    "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "mime_type": "application/pdf",
    "filename": "invoice-A1B2C3.pdf"
  },
  "created_at": "2026-08-25T09:15:02Z"
}

Feld	Was es enthält
id	Die gespeicherte Datei, als media_id beim Abrufen der Bytes zu übergeben
url	Eine Bird-URL, abzurufen mit Ihrem API-Schlüssel
mime_type	Der Medientyp, den WhatsApp für die Datei gemeldet hat, z. B. application/pdf
filename	Der Name, den der Absender der Datei gegeben hat; fehlt, wenn die Nachricht keinen enthielt
caption	Der Text, den der Kontakt unter dem Dokument eingegeben hat; fehlt, wenn keiner gesendet wurde

filename ist das einzige Feld, das Sende- und Empfangsseite unterschiedlich nutzen: Beim Senden ist es der Name, der im Chat angezeigt werden soll, und bei einer eingehenden Nachricht ist es das, was das Gerät des Kontakts übermittelt hat.

Die 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, zusammen mit den Redirect- und Header-Regeln, denen er folgt, und definiert das Aufbewahrungsfenster, in dem die Datei verfügbar ist.

Schreiben Sie filename nicht so wie es ankommt auf die Festplatte. Es handelt sich um von einem Angreifer kontrollierten Text eines nicht authentifizierten Absenders: Er kann Pfadtrenner, Traversierungssequenzen, eine irreführende zweite Erweiterung oder einen Namen enthalten, der mit einer bereits vorhandenen Datei kollidiert. Generieren Sie Ihren eigenen Speicherschlüssel aus der Medien-id, behalten Sie filename als Anzeige-Label bei und entscheiden Sie anhand von mime_type über die weitere Verarbeitung der Datei, nicht anhand der Erweiterung, die der Name vorgibt.

Der Webhook-Payload

whatsapp.received enthält den document-Zweig auf dem Event-Envelope:

Codebeispiel

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:15:02.336Z",
  "data": {
    "whatsapp_id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "document": {
      "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "mime_type": "application/pdf",
      "filename": "invoice-A1B2C3.pdf"
    },
    "tags": null,
    "metadata": null
  }
}

Ein Antrags- oder Onboarding-Flow, der Unterlagen einsammelt, kann hier auf mime_type routen und den Abruf in die Warteschlange stellen, da die Bytes für das gesamte Aufbewahrungsfenster verfügbar bleiben.

Worauf Sie achten sollten

mime_type ist der Bericht von WhatsApp über die Datei und sagt nichts über deren Inhalt aus. Scannen Sie alles, was Sie von einem Kontakt entgegennehmen, und validieren Sie die Struktur der Datei, bevor Sie sie parsen.
Beschriftung und Dateiname sind unterschiedliche Felder. Ein Kontakt, der beim Anhängen der Datei eine Notiz eintippt, füllt caption; filename stammt weiterhin vom Gerät.

Nächste Schritte

So funktioniert der Empfang: der eingehende Envelope, Medienabruf und der whatsapp.received-Webhook
WhatsApp-Dokumentnachrichten: die Sendeseite desselben Zweigs
Bilder empfangen: dieselbe Medienstruktur für ein Foto eines Dokuments
WhatsApp-Events: die vollständige Event-Liste, über API oder Webhooks