# Menerima dokumen WhatsApp

PDF, spreadsheet, atau file lain yang dilampirkan kontak tiba sebagai pesan masuk yang membawa `document`: referensi media bersama, beserta nama yang diberikan perangkat pengirim untuk file tersebut.

## Apa yang dibawa dokumen masuk

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

| Field       | Apa yang dibawanya                                                                    |
| ----------- | ------------------------------------------------------------------------------------- |
| `id`        | File yang disimpan, diteruskan sebagai `media_id` saat mengambil byte                 |
| `url`       | URL Bird, diambil dengan kunci API Anda                                               |
| `mime_type` | Tipe media yang dilaporkan WhatsApp untuk file tersebut, misalnya `application/pdf`   |
| `filename`  | Nama file dari pengirim; tidak ada jika pesan tidak menyertakannya                    |
| `caption`   | Teks yang diketik kontak di bawah dokumen; tidak ada jika mereka tidak mengirimkannya |

`filename` adalah satu-satunya field yang digunakan secara berbeda oleh sisi pengirim dan sisi penerima: pada pengiriman, field ini adalah nama yang ingin Anda tampilkan di chat, dan pada pesan masuk, field ini adalah apa pun yang diberikan perangkat kontak.

## Mengambil byte

Teruskan ID pesan dan `id` media ke metode media channel. Panduan hub [mengambil media masuk](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) memuat pemanggilan tersebut dalam setiap bahasa, beserta aturan redirect dan header yang diikutinya, dan mengatur jendela retensi tempat file disimpan.

**Jangan tulis `filename` ke disk begitu tiba.** Teks ini dikontrol penyerang dari pengirim yang tidak terautentikasi: bisa berisi pemisah path, urutan traversal, ekstensi kedua yang menyesatkan, atau nama yang bertabrakan dengan file yang sudah Anda miliki. Buat kunci penyimpanan Anda sendiri dari `id` media, simpan `filename` sebagai label tampilan, dan tentukan tindakan terhadap file berdasarkan `mime_type`, bukan dari ekstensi yang diklaim namanya.

## Payload webhook

`whatsapp.received` membawa arm `document` pada envelope event:

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

Alur klaim atau onboarding yang mengumpulkan dokumen dapat melakukan routing berdasarkan `mime_type` di sini dan mengantrikan pengambilan, karena byte tetap tersedia selama jendela retensi berlaku.

## Hal yang perlu diperhatikan

- **`mime_type` adalah laporan WhatsApp tentang file, dan tidak menjelaskan apa yang ada di dalamnya.** Pindai semua yang Anda terima dari kontak, dan validasi struktur file itu sendiri sebelum mem-parsing-nya.
- **Caption dan nama file adalah field yang berbeda.** Kontak yang mengetik catatan saat melampirkan file mengisi `caption`; `filename` tetap berasal dari perangkat mereka.

## Langkah selanjutnya

- [Cara kerja penerimaan](/docs/guides/whatsapp/receiving-whatsapp): envelope masuk, pengambilan media, dan webhook `whatsapp.received`
- [Pesan dokumen WhatsApp](/docs/guides/whatsapp/message-types/documents): sisi pengiriman dari arm yang sama
- [Menerima gambar](/docs/guides/whatsapp/receiving-whatsapp/images): bentuk media yang sama untuk foto dokumen
- [Event WhatsApp](/docs/guides/whatsapp/events): daftar event lengkap, melalui API atau webhook

## 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)