# Wiadomości dokumentowe WhatsApp Wiadomość dokumentowa zawiera publiczny URL, który WhatsApp pobiera w momencie wysyłki, z opcjonalnym podpisem i opcjonalną nazwą pliku. To największy typ mediów i jedyny, który obsługuje zarówno podpis, jak i nazwę pliku. ## Wyślij dokument Ustaw `document.url`: **TypeScript** ```typescript const msg = await bird.whatsapp.send({ to: "+16505551234", from: "+13124495648", document: { url: "https://cdn.example.com/invoices/a1b2c3.pdf" }, }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.ts.md) · [Python](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.py.md) · [Go](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.go.md) · [PHP](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.php.md) · [CLI](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.cli.md) · [MCP](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.mcp.md) · [cURL](/pl-pl/dokumentacja/guides/whatsapp/message-types/documents.curl.md) Pełna struktura dodaje `caption` i `filename`: ```json { "to": "+16505551234", "from": "+13124495648", "document": { "url": "https://cdn.example.com/invoices/a1b2c3.pdf", "caption": "Your invoice for order A1B2C3", "filename": "invoice-a1b2c3.pdf" } } ``` `from` jest wymagany w każdej wiadomości serwisowej: numer należący do Twojego obszaru roboczego, nie zarządzany przez Bird. ## Limity | Pole | Ograniczenie | Sprawdzane przez | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Rozmiar pliku | 100 MB | tylko WhatsApp, przy pobraniu (async) | | Typ pliku | PDF, Word, Excel, PowerPoint lub zwykły tekst wyświetlają się poprawnie w kliencie WhatsApp; inne typy są przesyłane, ale nie są obsługiwane | tylko WhatsApp, przy pobraniu (async) | | `caption` | do 1024 znaków | Bird, przy przyjęciu (`422`) | | `filename` | od 1 do 100 znaków | Bird, przy przyjęciu (`422`); ten limit to własny wybór Bird, ponieważ WhatsApp nie dokumentuje limitu nazwy pliku | | `url` | bezwzględny, `https`, zawiera host, bez surowych spacji | Bird, przy przyjęciu (`422`) | Bird sprawdza strukturę URL-a oraz długość podpisu i nazwy pliku, zanim cokolwiek trafi do kolejki. Nie sprawdza faktycznego rozmiaru ani typu pliku; może to zrobić dopiero WhatsApp przy pobraniu w momencie wysyłki. Zobacz w hubie [wysyłanie mediów przez URL](/docs/guides/whatsapp/message-types#sending-media-by-url) i [gdy media się nie dostarczą](/docs/guides/whatsapp/message-types#when-media-fails). ## Odczyt dokumentu przychodzącego Dokument przychodzący zawiera ten sam obiekt `document` oraz `id` i `mime_type`, które Bird uzyskał pobierając plik. Oba są nieobecne przy odczycie wiadomości wychodzącej, ponieważ Bird nigdy nie pobrał pliku, który wysłał, a `filename` w dokumencie przychodzącym to wartość dostarczona przez urządzenie kontaktu. Zobacz [Odbieranie dokumentów WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/documents), aby poznać pełny odczyt przychodzący, ładunek `whatsapp.received` i na co zwrócić uwagę. ## Limity i tryby błędów - **Okno obsługi klienta musi być otwarte.** Dokumenty to wiadomości serwisowe, dostarczalne tylko w otwartym oknie; zobacz w hubie [okno obsługi klienta](/docs/guides/whatsapp/message-types#the-customer-service-window). - **Bird odrzuca `http`; WhatsApp sam by go pobrał.** Zobacz w hubie [wysyłanie mediów przez URL](/docs/guides/whatsapp/message-types#sending-media-by-url), aby poznać pełną weryfikację struktury. - **Nieudane pobranie i tak jest naliczane, a ten typ mediów najczęściej na to trafia.** Przy 100 MB dokument to największy obiekt, jaki możesz wysłać, a Bird nie sprawdza faktycznych bajtów przy przyjęciu. Zobacz w hubie [gdy media się nie dostarczą](/docs/guides/whatsapp/message-types#when-media-fails), aby poznać `media_rejected` i fakt naliczania opłaty przy błędzie. Własny tekst odrzucenia dokumentu z WhatsApp nie został niezależnie zmierzony tak jak w przypadku obrazów, więc traktuj mapowanie jako wywnioskowane przez analogię, a nie potwierdzone dla każdego przypadku. - **Pominięcie `filename` nie oznacza, że odbiorca nie widzi żadnej nazwy.** WhatsApp wyprowadza ją ze ścieżki URL-a, co może dać nieprzejrzysty hash lub slug zamiast czytelnej nazwy. Ustaw `filename` jawnie, aby kontrolować to, co faktycznie się wyświetla. - **Limit 100 znaków dla `filename` to własny wybór Bird, a nie ograniczenie WhatsApp.** WhatsApp w ogóle nie dokumentuje limitu długości nazwy pliku. - **WhatsApp przechowuje pobrany URL w pamięci podręcznej przez około 10 minut.** Ponowne wysłanie tego samego URL-a w tym oknie zwraca wynik pierwszego pobrania; zmień URL, aby wymusić nowe pobranie. ## Następne kroki - [Wiadomości serwisowe WhatsApp](/docs/guides/whatsapp/message-types): okno obsługi klienta i model wspólny dla każdej wiadomości serwisowej - [Obrazy](/docs/guides/whatsapp/message-types/images): gdy chcesz wysłać zdjęcie lub grafikę zamiast pliku - [Szablony](/docs/guides/whatsapp/templates): wiadomości, które możesz wysyłać po zamknięciu okna - [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp): koperta żądania, model `202` i bezpieczne ponawianie ## 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)