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
| Typ | Bird interactive.type | Nagłówek | Stopka | Maks. treści |
|---|---|---|---|---|
| Przyciski odpowiedzi | button | tekst, obraz, wideo, dokument | tak | 1024 |
| Menu list | list | tylko tekst | tak | 4096 |
| Przyciski z linkiem | cta_url | tekst, obraz, wideo, dokument | tak | 1024 |
| Karuzele multimedialne | carousel | brak w wiadomości; obraz lub wideo na kartę | nie | 1024 wiadomość, 160 na kartę |
| Żądania lokalizacji | location_request_message | brak | nie | 1024 |
| Żądania danych kontaktowych | request_contact_info | brak | nie | 1024 |
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);msg = client.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"}},
],
},
)
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: "+15551234567",
From: "+13124495648",
Interactive: &bird.WhatsAppInteractiveSend{
Type: "button",
BodyText: "Your gardening workshop is scheduled for 9am tomorrow.",
Buttons: &[]bird.WhatsAppInteractiveButtonSend{
{Type: "quick_reply", QuickReply: &bird.WhatsAppInteractiveQuickReplyButtonSend{Slug: "change-booking", Text: "Change"}},
{Type: "quick_reply", QuickReply: &bird.WhatsAppInteractiveQuickReplyButtonSend{Slug: "cancel-booking", Text: "Cancel"}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$interactive = (new WhatsAppMessageSendRequestInteractive())
->setType('button')
->setBodyText('Your gardening workshop is scheduled for 9am tomorrow.')
->setButtons([
(new WhatsAppInteractiveButtonSend())
->setType('quick_reply')
->setQuickReply((new WhatsAppInteractiveButtonSendQuickReply())->setSlug('change-booking')->setText('Change')),
(new WhatsAppInteractiveButtonSend())
->setType('quick_reply')
->setQuickReply((new WhatsAppInteractiveButtonSendQuickReply())->setSlug('cancel-booking')->setText('Cancel')),
]);
$message = $bird->whatsapp->send(
to: '+15551234567',
from: '+13124495648',
interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--interactive '{"body_text":"Your gardening workshop is scheduled for 9am tomorrow.","buttons":[{"quick_reply":{"slug":"change-booking","text":"Change"},"type":"quick_reply"},{"quick_reply":{"slug":"cancel-booking","text":"Cancel"},"type":"quick_reply"}],"type":"button"}' \
--to +15551234567{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"interactive": {
"body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
"buttons": [
{
"quick_reply": {
"slug": "change-booking",
"text": "Change"
},
"type": "quick_reply"
},
{
"quick_reply": {
"slug": "cancel-booking",
"text": "Cancel"
},
"type": "quick_reply"
}
],
"type": "button"
},
"to": "+15551234567"
}
}curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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" } }
]
}
}'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ć.
| Kod | Status | Co go wywołuje | Dotyczy |
|---|---|---|---|
| E15055 WhatsAppInteractiveLimitExceeded | 422 | Wiadomość przekracza limit dla swojego typu; aktualnie ponad 10 wierszy w sekcjach listy. | Tylko menu list |
| E15056 WhatsAppInteractiveDuplicateLabel | 422 | Dwa 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 WhatsAppInteractiveCarouselButtonsMismatch | 422 | Karty 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
- Wysyłanie wiadomości WhatsApp: koperta żądania, model 202 i bezpieczne ponawianie
- Zdarzenia WhatsApp: śledź dostarczenie wiadomości przez API lub webhooki
- Szablony WhatsApp: wiadomości, które nadal możesz wysłać po zamknięciu okna
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