# WhatsApp-documenten ontvangen

Een pdf, spreadsheet of elk ander bestand dat een contact bijvoegt, komt binnen als een inkomend bericht met `document`: de gedeelde mediareferentie, plus de naam die het eigen apparaat aan het bestand heeft gegeven.

## Wat een inkomend document bevat

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

| Veld        | Wat het bevat                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------- |
| `id`        | Het opgeslagen bestand, mee te geven als `media_id` bij het ophalen van de bytes              |
| `url`       | Een Bird-URL, op te halen met je API-key                                                      |
| `mime_type` | Het mediatype dat WhatsApp voor het bestand heeft gerapporteerd, zoals `application/pdf`      |
| `filename`  | De eigen naam van de afzender voor het bestand; afwezig als het bericht er geen bevatte       |
| `caption`   | De tekst die het contact onder het document heeft getypt; afwezig als die niet is meegestuurd |

`filename` is het enige veld dat de verzendkant en de ontvangstkant anders gebruiken: bij een verzending is het de naam die je in de chat wilt tonen, en bij een inkomend bericht is het wat het apparaat van het contact heeft meegeleverd.

## De bytes ophalen

Geef het bericht-ID en de media-`id` door aan de mediamethode van het kanaal. De hub's [inkomende media ophalen](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) bevat die aanroep in elke taal, samen met de redirect- en headerregels die worden gevolgd, en bepaalt het bewaarvenster waarin het bestand beschikbaar blijft.

**Schrijf `filename` niet naar schijf zoals het binnenkomt.** Het is door een aanvaller bestuurbare tekst van een niet-geauthenticeerde afzender: het kan padscheidingstekens, traversal-reeksen, een misleidende tweede extensie of een naam bevatten die botst met een bestand dat je al hebt. Genereer je eigen opslagsleutel op basis van de media-`id`, bewaar `filename` als weergavelabel en bepaal wat je met het bestand doet op basis van `mime_type` in plaats van de extensie die de naam claimt.

## De webhook-payload

`whatsapp.received` bevat de `document`-arm op de 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
  }
}
```

Een claim- of onboardingflow die documenten verzamelt, kan hier routeren op `mime_type` en het ophalen in de wachtrij plaatsen, aangezien de bytes beschikbaar blijven gedurende het hele bewaarvenster.

## Aandachtspunten

- **`mime_type` is het rapport van WhatsApp over het bestand en zegt niets over wat erin zit.** Scan alles wat je van een contact accepteert en valideer de eigen structuur van het bestand voordat je het parst.
- **Een bijschrift en een bestandsnaam zijn verschillende velden.** Een contact dat een notitie typt bij het bijvoegen van het bestand vult `caption`; `filename` komt nog steeds van het apparaat.

## Vervolgstappen

- [Hoe ontvangen werkt](/docs/guides/whatsapp/receiving-whatsapp): de inkomende envelope, media ophalen en de `whatsapp.received`-webhook
- [WhatsApp-documentberichten](/docs/guides/whatsapp/message-types/documents): de verzendzijde van dezelfde arm
- [Afbeeldingen ontvangen](/docs/guides/whatsapp/receiving-whatsapp/images): dezelfde mediavorm voor een foto van een document
- [WhatsApp-events](/docs/guides/whatsapp/events): de volledige eventlijst, via de API of 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)