Sign inGet started

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:
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);
Pełna struktura dodaje caption i filename:
Przykład kodu
{
  "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

PoleOgraniczenieSprawdzane przez
Rozmiar pliku100 MBtylko WhatsApp, przy pobraniu (async)
Typ plikuPDF, Word, Excel, PowerPoint lub zwykły tekst wyświetlają się poprawnie w kliencie WhatsApp; inne typy są przesyłane, ale nie są obsługiwanetylko WhatsApp, przy pobraniu (async)
captiondo 1024 znakówBird, przy przyjęciu (422)
filenameod 1 do 100 znakówBird, przy przyjęciu (422); ten limit to własny wybór Bird, ponieważ WhatsApp nie dokumentuje limitu nazwy pliku
urlbezwzględny, https, zawiera host, bez surowych spacjiBird, 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 i gdy media się nie dostarczą.

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, 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.
  • Bird odrzuca http; WhatsApp sam by go pobrał. Zobacz w hubie wysyłanie mediów przez 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ą, 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