# 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

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

| 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](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) 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:

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

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](/docs/guides/whatsapp/receiving-whatsapp): koperta wiadomości przychodzącej, pobieranie mediów i webhook `whatsapp.received`
- [Wiadomości dokumentowe WhatsApp](/docs/guides/whatsapp/message-types/documents): strona wysyłania tej samej gałęzi
- [Odbieranie obrazów](/docs/guides/whatsapp/receiving-whatsapp/images): ten sam kształt mediów dla zdjęcia dokumentu
- [Zdarzenia WhatsApp](/docs/guides/whatsapp/events): pełna lista zdarzeń, przez API lub webhooki

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