# 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

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) 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:

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp): der eingehende Envelope, Medienabruf und der `whatsapp.received`-Webhook
- [WhatsApp-Dokumentnachrichten](/docs/guides/whatsapp/message-types/documents): die Sendeseite desselben Zweigs
- [Bilder empfangen](/docs/guides/whatsapp/receiving-whatsapp/images): dieselbe Medienstruktur für ein Foto eines Dokuments
- [WhatsApp-Events](/docs/guides/whatsapp/events): die vollständige Event-Liste, über API oder Webhooks

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)