Sign inGet started

Przyciski szybkiej odpowiedzi WhatsApp

Przyciski szybkiej odpowiedzi umieszczają do trzech wybieralnych opcji pod wiadomością WhatsApp, dzięki czemu odbiorca odpowiada jednym dotknięciem zamiast wpisywać tekst. Używaj ich do szybkich decyzji, takich jak potwierdzenie lub anulowanie rezerwacji. Jeśli potrzebujesz więcej niż trzech opcji, użyj menu list.

Wysyłanie przycisków szybkiej odpowiedzi

Ustaw interactive.type na button z polem body_text i od jednego do trzech buttons, każdy jako quick_reply:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  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" } }],
  },
});
console.log(msg.id, msg.status);
from jest wymagane w każdej wiadomości serwisowej: numer należący do Twojego obszaru roboczego, nie zarządzany przez Bird. Pełna struktura dodaje opcjonalny nagłówek, stopkę, cytat wcześniejszej wiadomości i drugi przycisk:
Przykład kodu
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
    "footer_text": "Lucky Shrub, your gateway to succulents",
    "buttons": [
      { "type": "quick_reply", "quick_reply": { "slug": "change-booking", "text": "Change" } },
      { "type": "quick_reply", "quick_reply": { "slug": "cancel-booking", "text": "Cancel" } }
    ]
  },
  "tags": [{ "name": "category", "value": "booking" }],
  "metadata": { "order_id": "A-1" }
}
in_reply_to_message_id cytuje wcześniejszą wiadomość w tej samej konwersacji. Zobacz w hubie cytowanie wiadomości w celu powiązania odpowiedzi, aby dowiedzieć się, jak działa rozwiązywanie i czego może nie uwzględnić.
Ten typ wysyła wyłącznie przyciski quick_reply. Przycisk cta_url należy do osobnego interactive.type i nie może występować obok buttons; zobacz sekcję przyciski w hubie, aby poznać wspólną strukturę przycisków.

Nagłówki i stopki

Nagłówek jest opcjonalny i przyjmuje jedną z czterech postaci:
Przykład kodu
"header": { "type": "text",     "text": "New workshop dates" }
"header": { "type": "image",    "url": "https://cdn.example.com/a.png" }
"header": { "type": "video",    "url": "https://cdn.example.com/a.mp4" }
"header": { "type": "document", "url": "https://cdn.example.com/a.pdf" }
Nagłówek multimedialny (image, video lub document) przekazuje plik jako publiczny URL https, który WhatsApp pobiera w momencie wysyłki, zamiast przesłanego uchwytu multimediów. footer_text jest opcjonalne i dodaje wiersz pod przyciskami.

Limity

PoleOgraniczenie
buttonsod 1 do 3 wpisów, każdy jako quick_reply
quick_reply.slugwymagane, od 1 do 256 znaków
quick_reply.text (etykieta)wymagane, od 1 do 20 znaków, unikalne w obrębie wiadomości
body_textwymagane, od 1 do 1024 znaków
footer_textopcjonalne, od 1 do 60 znaków
header.textod 1 do 60 znaków
Bird sprawdza, czy etykiety przycisków (quick_reply.text) są unikalne, ale nie sprawdza, czy wartości slug są unikalne, mimo że każdy slug ma identyfikować jeden przycisk. Dwa przyciski ze wspólnym slugiem są wysyłane i dostarczane, a ich odpowiedzi wracają nierozróżnialne.

Odczytywanie odpowiedzi

Naciśnięcie przycisku dociera jako osobna wiadomość przychodząca, zawierająca interactive_reply:
Przykład kodu
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive_reply": {
    "type": "button",
    "button": {
      "slug": "cancel-booking",
      "text": "Cancel"
    }
  },
  "created_at": "2026-08-25T09:04:11Z"
}
slug ustawiony przy wysyłce wraca bez zmian, więc możesz rozgałęziać logikę bezpośrednio na jego podstawie, bez tablicy mapowań. Odpowiedź zobaczysz na liście wiadomości lub przez GET /v1/whatsapp/messages/{id}; zobacz w hubie odczytywanie odpowiedzi, aby poznać pełną ścieżkę.

Limity i przypadki brzegowe

  • Okno obsługi klienta musi być otwarte. Przyciski szybkiej odpowiedzi to wiadomość serwisowa, dostarczalna tylko w otwartym oknie; zobacz okno obsługi klienta w hubie. Sprawdzenie okna nie blokuje wysyłki, więc 202 nie jest dowodem, że okno było faktycznie otwarte w momencie wysyłki.
  • from musi być numerem należącym do Twojego obszaru roboczego. Pominięcie go lub podanie numeru, który nie jest podłączonym nadawcą, powoduje odrzucenie przed utworzeniem wysyłki.
  • Etykiety muszą być unikalne, w przeciwnym razie wysyłka zostanie odrzucona. Dwa przyciski z tą samą wartością quick_reply.text kończą się błędem 422 E15056 WhatsAppInteractiveDuplicateLabel, ponieważ Meta odrzuciłaby duplikat już po zaakceptowaniu i naliczeniu opłaty za wysyłkę.
  • Etykieta jest tym, co widzi odbiorca; slug nigdy nie jest wyświetlany. Umieszczanie treści przeznaczonych dla użytkownika w slug nie daje żadnego efektu, ponieważ w czacie renderuje się tylko text.
  • URL nagłówka multimedialnego, którego WhatsApp nie może pobrać, kończy się błędem po zaakceptowaniu wysyłki. Bird nie waliduje nagłówka url tak jak waliduje URL wiadomości multimedialnej, więc URL http:// lub zwracający błąd przechodzi walidację żądania, a następnie kończy się niepowodzeniem asynchronicznie, z media_rejected na last_error wiadomości.
  • Wysyłanie własnych nazw pól Meta powoduje odrzucenie żądania. Ten typ odrzuca nieznane właściwości, więc JSON skopiowane z referencji Cloud API Meta, takie jak obiekt body lub wrapper action.buttons, wymaga przekształcenia do płaskich pól Bird.
Cytat, który nie zostanie rozwiązany, powoduje odrzucenie żądania zanim cokolwiek zostanie utworzone lub naliczone: 404 E15071, gdy podane id nie wskazuje żadnej wiadomości w tym obszarze roboczym, 422 E15072, gdy wskazuje wiadomość, której nie można cytować. Błędy wspólne dla każdej wysyłki WhatsApp, takie jak zamknięte okno, brakujący lub nieprawidłowy nadawca albo nieprawidłowy odbiorca, znajdziesz w hubie w sekcjach błędy i Wysyłanie wiadomości WhatsApp.

Następne kroki