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

Codevoorbeeld

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

Codevoorbeeld

{
  "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: de inkomende envelope, media ophalen en de whatsapp.received-webhook
WhatsApp-documentberichten: de verzendzijde van dezelfde arm
Afbeeldingen ontvangen: dezelfde mediavorm voor een foto van een document
WhatsApp-events: de volledige eventlijst, via de API of webhooks

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channel Begrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builder Ontdek de mogelijkheidWhatsApp

Probeer de oefening en ontvang een implementatieoverzicht