Sign inGet started

WhatsApp reply-knoppen

Reply-knoppen plaatsen maximaal drie tikbare keuzes onder een WhatsApp-bericht, zodat de ontvanger met een tik antwoordt in plaats van vrije tekst. Gebruik ze voor een snelle beslissing, zoals het bevestigen of annuleren van een boeking. Gebruik voor meer dan drie keuzes in plaats daarvan lijstmenu's.

Reply-knoppen versturen

Stel interactive.type in op button, met een body_text en één tot drie buttons, elk een 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 is verplicht bij elk servicebericht: een nummer dat je werkruimte bezit, geen door Bird beheerd nummer. De volledige structuur voegt een optionele header, footer, een citaat van een eerder bericht en een tweede knop toe:
Codevoorbeeld
{
  "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 citeert een eerder bericht in hetzelfde gesprek. Zie in de hub een bericht citeren om een antwoord te correleren voor hoe de resolutie werkt en wat die kan missen.
Dit type verstuurt alleen quick_reply-knoppen. Een cta_url-knop hoort bij een apart interactive.type en kan niet naast buttons verschijnen; zie de sectie knoppen in de hub voor de gedeelde knopstructuur.

Headers en footers

Een header is optioneel en heeft een van vier vormen:
Codevoorbeeld
"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" }
Een mediaheader (image, video of document) bevat het bestand als een publieke https-URL die WhatsApp op het moment van verzenden ophaalt, in plaats van een geüpload media-handle. footer_text is optioneel en voegt een regel toe onder de knoppen.

Limieten

VeldBegrenzing
buttons1 tot 3 items, elk een quick_reply
quick_reply.slugverplicht, 1 tot 256 tekens
quick_reply.text (label)verplicht, 1 tot 20 tekens, uniek binnen het bericht
body_textverplicht, 1 tot 1024 tekens
footer_textoptioneel, 1 tot 60 tekens
header.text1 tot 60 tekens
Bird controleert of knoplabels (quick_reply.text) uniek zijn, maar controleert niet of slug-waarden uniek zijn, hoewel elke slug bedoeld is om één knop te identificeren. Twee knoppen met dezelfde slug worden allebei verstuurd en afgeleverd, en hun antwoorden komen ononderscheidbaar terug.

Het antwoord lezen

Een druk op een knop komt binnen als een eigen inkomend bericht, met interactive_reply:
Codevoorbeeld
{
  "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"
}
De slug die je bij het verzenden instelt, komt letterlijk terug, zodat je er direct op kunt branchen zonder opzoektabel. Je ziet dit antwoord via de berichtenlijst of GET /v1/whatsapp/messages/{id}; zie in de hub een antwoord lezen voor het volledige pad.

Limieten en randgevallen

  • Het klantenservicevenster moet open zijn. Reply-knoppen zijn een servicebericht en kunnen alleen binnen een open venster worden afgeleverd; zie in de hub klantenservicevenster. De venstercontrole faalt open, dus een 202 is geen bewijs dat het venster daadwerkelijk open was toen het bericht werd verstuurd.
  • from moet een nummer zijn dat je werkruimte bezit. Als je het weglaat of een nummer opgeeft dat geen verbonden afzender is, wordt het geweigerd voordat de verzending wordt aangemaakt.
  • Labels moeten uniek zijn, anders wordt de verzending geweigerd. Twee knoppen met hetzelfde quick_reply.text mislukken met 422 E15056 WhatsAppInteractiveDuplicateLabel, omdat Meta het duplicaat anders zou afwijzen nadat de verzending al is geaccepteerd en in rekening is gebracht.
  • Het label is wat de ontvanger ziet; de slug nooit. Gebruikersgerichte tekst in slug plaatsen is een stille no-op, want alleen text wordt weergegeven in de chat.
  • Een mediaheader-URL die WhatsApp niet kan ophalen, mislukt nadat de verzending is geaccepteerd. Bird valideert de header-url niet op dezelfde manier als de URL van een mediabericht, dus een http://-URL of een URL die een fout retourneert, passeert het verzoek en mislukt vervolgens asynchroon, met media_rejected op de last_error van het bericht.
  • Meta's eigen veldnamen meesturen laat het verzoek mislukken. Dit type weigert onbekende properties direct, dus JSON gekopieerd uit Meta's Cloud API-referentie, zoals een body-object of een action.buttons-wrapper, moet eerst worden omgezet naar de platte velden van Bird.
Een citaat dat niet kan worden opgelost, laat het verzoek mislukken voordat er iets wordt aangemaakt of in rekening wordt gebracht: 404 E15071 wanneer het id geen bericht noemt dat deze werkruimte bevat, 422 E15072 wanneer het een bericht noemt dat niet kan worden geciteerd. Zie voor de fouten die elke WhatsApp-verzending kan tegenkomen, zoals een gesloten venster, een ontbrekende of ongeldige afzender, of een ongeldige ontvanger, de hub's fouten en WhatsApp-berichten versturen.

Vervolgstappen