Sign inGet started

Wiadomości interaktywne WhatsApp

Wiadomość interaktywna to tekst treści plus element do kliknięcia przez odbiorcę: przycisk WhatsApp, menu, link, karta lub żądanie lokalizacji albo danych kontaktowych. Tam, gdzie odpowiedź szablonowa wymaga parsowania dowolnego tekstu, menu WhatsApp lub zestaw przycisków WhatsApp daje odbiorcy ustalony zbiór opcji, a tobie zwraca wartość, którą sam zdefiniowałeś. Ta strona opisuje cechy wspólne sześciu typów; strona każdego typu opisuje jego kształt na poziomie protokołu i jego własne ograniczenia.

Sześć typów

TypBird interactive.typeNagłówekStopkaMaks. treści
Przyciski odpowiedzibuttontekst, obraz, wideo, dokumenttak1024
Menu listlisttylko teksttak4096
Przyciski z linkiemcta_urltekst, obraz, wideo, dokumenttak1024
Karuzele multimedialnecarouselbrak w wiadomości; obraz lub wideo na kartęnie1024 wiadomość, 160 na kartę
Żądania lokalizacjilocation_request_messagebraknie1024
Żądania danych kontaktowychrequest_contact_infobraknie1024
Każdy typ jest treścią dowolną: można go dostarczyć tylko w otwartym oknie obsługi klienta i nigdy nie podlega weryfikacji przez Meta tak jak szablon.
Wiadomości interaktywne to treść dowolna, więc obowiązuje reguła okna obsługi klienta: zobacz okno obsługi klienta, aby dowiedzieć się, co to oznacza i co zwraca zamknięte okno.
Każde interaktywne wysłanie wymaga też from, numeru należącego do twojego obszaru roboczego. Numery zarządzane przez Bird nie obsługują tej funkcji, więc do interaktywnego wysłania potrzebujesz najpierw podłączonego własnego numeru.

Gałąź treści interaktywnej

interactive to jedno z wzajemnie wykluczających się pól treści w POST /v1/whatsapp/messages, obok template, text, image i pozostałych: dokładnie jedno może być obecne w wysyłce. Wewnątrz interactive pole type wskazuje, który z sześciu wariantów to jest, a pole tego wariantu zawiera resztę (buttons, list, cta_url lub cards). Schemat blokuje pola każdego innego wariantu, więc mieszanie dwóch wariantów w jednej wysyłce kończy się błędem walidacji, zanim żądanie dotrze do handlera.
Kopertę żądania, model odpowiedzi 202 i bezpieczne ponawianie znajdziesz na stronie Wysyłanie wiadomości WhatsApp, a nie na tej stronie.
Oto minimalna wiadomość interaktywna: dwa przyciski WhatsApp w wysyłce z przyciskami odpowiedzi, po jednym języku naraz.
const msg = await bird.whatsapp.send({
  to: "+15551234567",
  from: "+13124495648",
  interactive: {
    type: "button",
    body_text: "Your gardening workshop is scheduled for 9am tomorrow.",
    buttons: [
      { type: "quick_reply", quick_reply: { slug: "change-booking", text: "Change" } },
      { type: "quick_reply", quick_reply: { slug: "cancel-booking", text: "Cancel" } },
    ],
  },
});
console.log(msg.id, msg.status);

Przyciski

Cztery z sześciu typów umieszczają przycisk i wszystkie korzystają z tego samego kształtu: obiektu z dyskryminatorem, którego type to quick_reply lub cta_url, każdy z własnym zagnieżdżonym polem o tej samej nazwie. Przycisk quick_reply zawiera slug i text; przycisk cta_url zawiera text i url. Które typy akceptują który kształt przycisku:
  • Przyciski odpowiedzi wysyłają tylko przyciski quick_reply, od 1 do 3.
  • Przyciski z linkiem wysyłają dokładnie jeden przycisk cta_url.
  • Karuzele multimedialne umieszczają przyciski na każdej karcie: albo jeden przycisk cta_url, albo do trzech przycisków quick_reply, przy czym każda karta w karuzeli musi być zgodna.
  • Menu list używają wierszy wewnątrz sekcji zamiast tego obiektu przycisku; szczegóły na ich własnej stronie.
Pole slug przycisku quick_reply to twój własny identyfikator tego przycisku. Nigdy nie jest pokazywane odbiorcy; widoczna jest tylko etykieta text, a slug jest zwracane dosłownie w odpowiedzi. To właśnie ten obieg pozwala powiązać odpowiedź z przyciskiem, który ją wywołał, dlatego warto powiedzieć o tym raz, tutaj, a nie na każdej stronie poszczególnego typu.

Odczytywanie odpowiedzi

Naciśnięcie przycisku lub wybranie wiersza z menu wysyła osobną wiadomość przychodzącą z obiektem interactive_reply. interactive_reply.type to button lub list; niezależnie od wartości, zagnieżdżony obiekt zawiera zadeklarowane przez ciebie slug i text, czyli klikniętą etykietę, którą odbiorca faktycznie widział. Dwa typy żądań, żądania lokalizacji i żądania danych kontaktowych, odpowiadają inaczej: odpowiedź na żądanie lokalizacji to zwykła przychodząca wiadomość lokalizacji, a odpowiedź na żądanie danych kontaktowych to przychodząca wizytówka, a nie interactive_reply.
Odpowiedź dociera do ciebie przez listę wiadomości i GET /v1/whatsapp/messages/{id}, tak samo jak każda przychodząca wiadomość WhatsApp. Aby reagować na nią w momencie nadejścia zamiast odpytywać, zasubskrybuj webhook whatsapp.received: jego payload zawiera interactive_reply, więc już wskazuje kliknięty przycisk lub wiersz. Odbieranie interaktywnych odpowiedzi opisuje kształt odczytu kliknięcia, payload webhooka i kliknięcia docierające na innej gałęzi.

Cytowanie wiadomości w celu powiązania odpowiedzi

in_reply_to_message_id w wysyłce cytuje wcześniejszą wiadomość z tej samej konwersacji, a każda wiadomość, wysłana lub odebrana, zwraca je przy odczycie. To jedno pole dla obu kierunków.
Korelacja, którą to daje, jest asymetryczna. Kliknięcie przycisku WhatsApp lub wiersza menu niesie własne context od Meta, więc in_reply_to_message_id wskazuje wiadomość, która je zaoferowała. Udostępniona wizytówka nie niesie żadnego context, więc nie wskazuje niczego: odpowiedź na żądanie danych kontaktowych korelujesz po from i czasie, nie po tym polu.
Rozwiązywanie odbywa się przez magazyn kontekstu wiadomości, a brak dopasowania pomija pole zamiast je zgłaszać. Na poziomie protokołu jest to nieodróżnialne od odpowiedzi, która niczego nie dotyczy. Integracja wymagająca niezawodnej korelacji nie powinna polegać wyłącznie na tym polu: dodaj własne metadata do wysyłki i dopasowuj po nim.
Okno, w którym wiadomość pozostaje cytowalna, jest ograniczone do 15 dni; po tym czasie wysyłka kończy się błędem 404 E15071, ponieważ Bird nie przechowuje już identyfikatora dostawcy potrzebnego do cytatu. Strona Wysyłanie wiadomości WhatsApp opisuje pole po stronie wysyłki: jego długość, rozwiązywanie i kształt żądania.

Błędy

Trzy kody błędów dotyczą wyłącznie treści interaktywnej. Każdy z nich uruchamia się tylko dla typów, które mają sprawdzane pole, dlatego czwarta kolumna wskazuje, które typy mogą faktycznie go wywołać.
KodStatusCo go wywołujeDotyczy
E15055 WhatsAppInteractiveLimitExceeded422Wiadomość przekracza limit dla swojego typu; aktualnie ponad 10 wierszy w sekcjach listy.Tylko menu list
E15056 WhatsAppInteractiveDuplicateLabel422Dwa przyciski lub wiersze w tej samej wiadomości mają tę samą etykietę.Każdy typ z etykietowanymi przyciskami lub wierszami: przyciski odpowiedzi, menu list, karuzele multimedialne
E15059 WhatsAppInteractiveCarouselButtonsMismatch422Karty karuzeli nie mają jednakowych przycisków.Tylko karuzele multimedialne
Każde interaktywne wysłanie może też trafić na błędy wspólne dla każdej wysyłki WhatsApp: zamknięte okno obsługi klienta, brakujący lub nieprawidłowy nadawca, nieprawidłowy odbiorca albo niejednoznaczna treść. Są one wspólne dla wszystkich typów treści WhatsApp, nie tylko dla wiadomości interaktywnych; zobacz Wysyłanie wiadomości WhatsApp, aby poznać tę listę bez jej powielania tutaj.

Następne kroki