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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
document={"url": "https://cdn.example.com/invoices/a1b2c3.pdf"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Document: &bird.WhatsAppDocumentSend{Url: "https://cdn.example.com/invoices/a1b2c3.pdf"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$document = (new WhatsAppMessageSendRequestDocument())
->setUrl('https://cdn.example.com/invoices/a1b2c3.pdf');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
document: $document,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--document https://cdn.example.com/invoices/a1b2c3.pdf \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
},
"from": "+13124495648",
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
}
}'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
| 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 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
- Wiadomości serwisowe WhatsApp: okno obsługi klienta i model wspólny dla każdej wiadomości serwisowej
- Obrazy: gdy chcesz wysłać zdjęcie lub grafikę zamiast pliku
- Szablony: wiadomości, które możesz wysyłać po zamknięciu okna
- Wysyłanie wiadomości WhatsApp: koperta żądania, model 202 i bezpieczne ponawianie
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