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
Contoh kode
{
"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 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:
Contoh kode
{
"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: envelope masuk, pengambilan media, dan webhook whatsapp.received
- Pesan dokumen WhatsApp: sisi pengiriman dari arm yang sama
- Menerima gambar: bentuk media yang sama untuk foto dokumen
- Event WhatsApp: daftar event lengkap, melalui API atau webhook
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Tonton panduannyaConnecting WhatsApp to Bird: from buying a number to a live channelPahami konsepnyaWhat is the 24-hour customer service window on WhatsApp?Gunakan alatnyaWhatsApp message builderJelajahi kemampuannyaWhatsApp
Coba praktiknya dan dapatkan ringkasan implementasi