Wiadomości serwisowe WhatsApp

Wiadomość serwisowa to wszystko, co wysyłasz poza zatwierdzonym szablonem: dowolna treść, którą firma wysyła w ramach otwartej konwersacji. POST /v1/whatsapp/messages przenosi dokładnie jeden z dziewięciu typów treści wiadomości serwisowej albo szablon. Ta strona opisuje cechy wspólne tych dziewięciu typów; strona każdego z nich opisuje jego format na łączu i własne ograniczenia.

Żądanie zawiera dokładnie jedno z pól template albo jedno z tych dziewięciu pól. Żądanie, które nie zawiera żadnego z nich lub zawiera więcej niż jedno, jest odrzucane z 422.

Wiadomość serwisowa, czyli dowolny z dziewięciu powyższych typów, jest dostarczana wyłącznie w ramach otwartego 24-godzinnego okna obsługi klienta. Kontakt otwiera to okno, wysyłając wiadomość lub dzwoniąc na numer Twojej firmy, a każda kolejna wiadomość od niego resetuje okno do 24 godzin.

Wiadomość serwisowa wysłana do zamkniętego okna jest odrzucana od razu: żądanie zwraca 422 E15044 WhatsAppServiceWindowClosed i nic nie zostaje utworzone ani naliczone. Wyślij zamiast tego zatwierdzony szablon; dotrze do kontaktu niezależnie od okna, a odpowiedź kontaktu otworzy je ponownie. Okno, które zamknie się w chwili między przyjęciem a wysyłką, też kończy się błędem, ale asynchronicznie: wiadomość osiąga failed z service_window_expired na last_error.

Sprawdzanie w momencie przyjęcia jest robione na zasadzie best effort, nie jest gwarancją: bramka przepuszcza w razie wątpliwości, więc brak danych w magazynie lub błąd odczytu pozwala na wysyłkę zamiast ją blokować. 202 nie jest więc dowodem, że okno było otwarte w momencie wysyłki; sygnałem ostatecznym jest status samej wiadomości, a nie odpowiedź na przyjęcie.

Każda wiadomość serwisowa wymaga też from, numeru należącego do Twojego obszaru roboczego. Numery zarządzane przez Bird nie mogą go przenosić, dlatego do wiadomości serwisowej potrzebujesz najpierw własnego podłączonego numeru; zobacz Konfiguracja numeru telefonu.

Zobacz okno obsługi klienta, aby poznać pełny cykl życia: jak okno się otwiera, co je resetuje i jak jest śledzone.

image, video, audio, sticker i document przyjmują url wskazujący na plik, który WhatsApp pobiera w momencie wysyłki, a nie plik przesłany wcześniej do Bird. Bird sprawdza format URL-a przy przyjęciu, zanim cokolwiek trafi do kolejki:

URL http jest odrzucany z 422 przy przyjęciu, mimo że WhatsApp pobrałby go bez problemu. To polityka Bird, a nie ograniczenie narzucone przez WhatsApp.

Bird nie sprawdza rozmiaru pliku, jego typu MIME ani tego, czy URL jest osiągalny. WhatsApp pobiera URL samodzielnie, gdy wysyła wiadomość, więc podpisany URL musi pozostać ważny po tym momencie, a nie tylko w chwili wysyłania żądania; prywatny lub wygasły URL kończy się błędem, gdy WhatsApp próbuje go pobrać. WhatsApp buforuje też pobrany URL przez ok. 10 minut, więc ponowne wysłanie tego samego URL-a w tym oknie serwuje pierwszy wynik zamiast pobierać ponownie.

Wysyłka multimediów podąża tą samą asynchroniczną ścieżką co każda wiadomość WhatsApp: Bird zwraca 202 i przyjmuje wiadomość, a następnie WhatsApp pobiera URL w momencie wysyłki. Jeśli to pobranie się nie powiedzie, wiadomość osiąga failed z media_rejected na last_error, czyli pod spodem 131053 od Meta.

media_rejected to ogólny kod obejmujący zbyt duży plik, 404, błąd DNS i nieprawidłowy typ MIME; Bird nie rozdziela go dalej, więc nie oczekuj osobnego kodu dla każdej przyczyny.

Asynchronicznie nieudana wysyłka multimediów i tak jest naliczana. Naliczanie następuje, gdy Bird przetworzy przyjętą wysyłkę, zanim WhatsApp w ogóle pobierze URL, i nie ma ścieżki zwrotu po zaksięgowaniu opłaty. Planuj budżet odpowiednio: wiadomość, która później nie powiedzie się w media_rejected, kosztuje tyle samo co dostarczona.

Wiadomość przychodząca zawiera jeden z tych samych dziewięciu typów, więc pole, które odczytujesz, odpowiada typowi użytemu przez kontakt. Wizytówki zwracane są w tym samym polu contact_cards niezależnie od tego, czy kontakt je udostępnił, czy Ty je wysłałeś. Odbieranie wiadomości WhatsApp opisuje odczytywanie wiadomości przychodzących przez API, pobieranie multimediów wysłanych przez kontakt oraz webhook whatsapp.received.