Odbieranie dokumentów WhatsApp
PDF, arkusz kalkulacyjny lub dowolny inny plik załączony przez kontakt dociera jako wiadomość przychodząca zawierająca document: współdzielone odwołanie do mediów oraz nazwę, którą nadało urządzenie kontaktu.
Co zawiera przychodzący dokument
Przykład kodu
{
"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"
}| Pole | Co zawiera |
|---|---|
| id | Zapisany plik, przekazywany jako media_id przy pobieraniu bajtów |
| url | URL Bird, pobierany z użyciem klucza API |
| mime_type | Typ mediów zgłoszony przez WhatsApp dla pliku, na przykład application/pdf |
| filename | Nazwa pliku nadana przez nadawcę; nieobecna, gdy wiadomość jej nie zawierała |
| caption | Tekst wpisany przez kontakt pod dokumentem; nieobecny, gdy go nie podał |
filename to jedyne pole, które strona wysyłająca i strona odbierająca wykorzystują inaczej: przy wysyłaniu jest to nazwa wyświetlana w czacie, a w wiadomości przychodzącej jest to cokolwiek, co dostarczyło urządzenie kontaktu.
Pobieranie bajtów
Przekaż identyfikator wiadomości i id mediów do metody mediów kanału. Sekcja huba pobieranie mediów przychodzących zawiera to wywołanie w każdym języku, wraz z regułami przekierowań i nagłówków, oraz określa okno retencji, w którym plik jest dostępny.
Nie zapisuj filename na dysk w niezmienionej formie. To tekst kontrolowany przez atakującego, pochodzący od nieuwierzytelnionego nadawcy: może zawierać separatory ścieżek, sekwencje przechodzenia katalogów, mylące drugie rozszerzenie lub nazwę kolidującą z plikiem, który już przechowujesz. Wygeneruj własny klucz przechowywania na podstawie id mediów, zachowaj filename jako etykietę wyświetlaną i decyduj o dalszym postępowaniu z plikiem na podstawie mime_type, a nie rozszerzenia podanego w nazwie.
Ładunek webhooka
whatsapp.received zawiera gałąź document w kopercie zdarzenia:
Przykład kodu
{
"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
}
}Przepływ zgłoszeń lub onboardingu zbierający dokumenty może kierować się polem mime_type i kolejkować pobranie, ponieważ bajty pozostają dostępne przez całe okno retencji.
Na co uważać
- mime_type to raport WhatsApp na temat pliku i nie mówi nic o tym, co jest w środku. Skanuj wszystko, co przyjmujesz od kontaktu, i zweryfikuj strukturę pliku przed jego parsowaniem.
- Podpis i nazwa pliku to różne pola. Kontakt, który wpisuje notatkę podczas załączania pliku, wypełnia caption; filename nadal pochodzi z jego urządzenia.
Następne kroki
- Jak działa odbieranie: koperta wiadomości przychodzącej, pobieranie mediów i webhook whatsapp.received
- Wiadomości dokumentowe WhatsApp: strona wysyłania tej samej gałęzi
- Odbieranie obrazów: ten sam kształt mediów dla zdjęcia dokumentu
- Zdarzenia WhatsApp: pełna lista zdarzeń, przez API lub webhooki
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy