Sign inGet started

WhatsApp linkbuttons

Een linkbutton plaatst één tikbare button onder een WhatsApp-bericht die een URL opent in de browser van de ontvanger. Gebruik hem wanneer de volgende stap op het web staat, zoals een afrekenpagina of een lijst met workshopdata, in plaats van in de chat zelf. Voor een keuze die de ontvanger binnen WhatsApp beantwoordt, gebruik je antwoordbuttons of lijstmenu's.

Een linkbutton versturen

Stel interactive.type in op cta_url, met een body_text- en een cta_url-object dat de text en url van de button bevat:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "cta_url",
    body_text: "Tap the button below to see the available dates.",
    cta_url: { text: "See dates", url: "https://example.com/workshops?click_id=a1b2c3" },
  },
});
console.log(msg.id, msg.status);
from is verplicht bij elk servicebericht: een nummer dat je werkruimte bezit, niet een door Bird beheerd nummer. De volledige vorm voegt een optionele header, footer en een citaat van een eerder bericht toe:
Codevoorbeeld
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Tap the button below to see the available dates.",
    "footer_text": "Dates are subject to change.",
    "cta_url": {
      "text": "See dates",
      "url": "https://example.com/workshops?click_id=a1b2c3"
    }
  },
  "tags": [{ "name": "campaign", "value": "autumn-workshops" }],
  "metadata": { "order_id": "A-4192" }
}
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 het kan missen.
Dit type verstuurt precies één cta_url-button en kan geen buttons, list of cards bevatten. Zie de sectie buttons in de hub voor de gedeelde buttonvorm, die ook door de eigen linkbutton van een carouselkaart wordt hergebruikt.

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 bij het versturen ophaalt, in plaats van een geüpload media-handle. footer_text is optioneel en voegt een regel toe onder de button.

Limieten

VeldLimiet
cta_url-buttonsprecies één
cta_url.text (label)verplicht, 1 tot 20 tekens
cta_url.urlverplicht, 1 tot 2000 tekens
body_textverplicht, 1 tot 1024 tekens
footer_textoptioneel, 1 tot 60 tekens
header.text1 tot 60 tekens
De limiet van 2000 tekens op url is van Bird zelf: Meta publiceert geen lengtelimiet voor dit veld. url controleert ook format: uri, een absoluut adres met een scheme, maar Bird controleert niet welk scheme: een http://-adres slaagt voor de validatie van Bird, en Meta is de enige die bepaalt of het wordt afgeleverd.

Wat een klik rapporteert

Een tik opent het adres in de browser van de ontvanger en er komt niets terug naar jou via de API. De tik op een linkbutton is geen interactive_reply: de inbound mapper die interactive_reply produceert verwerkt alleen een tik op een antwoordbutton en een tik op een lijstrij, en een cta_url-link heeft geen equivalent inbound-vorm. Wat je wel ziet is de gewone uitgaande levenscyclus, de sent-, delivered- en read-statussen van het bericht, maar read_at vertelt je dat het bericht is geopend, niet dat de button is getikt. Er is geen klikgebeurtenis, geen tijdstempel en geen tapsignaal per ontvanger van WhatsApp of van Bird.
Twee manieren om attributie terug te krijgen, aangezien de verzending zelf die niet geeft:
  • Instrumenteer de landingspagina. Het enige klikbewijs dat beschikbaar is, bevindt zich op je eigen bestemmingsserver, via de URL die je hebt meegegeven.
  • Varieer de URL zelf, per ontvanger. De url die je verstuurt is een letterlijke string: Bird slaat hem op en geeft hem ongewijzigd door aan Meta, zonder substitutie en zonder variabelesyntaxis. Hij is identiek voor elke ontvanger van één verzending, dus attributie per ontvanger betekent dat je zelf een queryparameter genereert, zoals ?click_id=<value>, en één POST /v1/whatsapp/messages-aanroep per ontvanger doet. Het endpoint accepteert al één to per aanroep, dus dit is boekhouding aan jouw kant en niet een ontbrekende API-functie.
Een derde optie bestaat helemaal buiten dit type: een template met een url-buttonvariabele wordt per ontvanger gepersonaliseerd door WhatsApp zelf, aangeleverd via de button-component van de verzending. Die variabele moet aan het einde van het adres staan, geschreven als {{1}}, zodat hij een afsluitend padsegment of querywaarde kan variëren maar nooit de host of het midden van de URL. De afweging: een template biedt per-ontvanger-URL's en aflevering buiten het klantenservicevenster, tegen de kosten van Meta's review en een vaste goedgekeurde vorm, terwijl een cta_url-verzending vrije-vormverzending zonder review biedt binnen een open venster met een URL die je zelf varieert.

Limieten en randgevallen

  • Het klantenservicevenster moet open zijn. Een linkbutton is een servicebericht dat alleen binnen een open venster kan worden afgeleverd; zie in de hub klantenservicevenster. De venstercontrole faalt open, dus een 202 is geen bewijs dat het venster daadwerkelijk open was toen de verzending plaatsvond.
  • from moet een nummer zijn dat je werkruimte bezit. Weglaten, of een nummer opgeven dat geen gekoppelde afzender is, wordt afgewezen voordat de verzending wordt aangemaakt.
  • De URL is statisch voor de hele verzending en identiek voor elke ontvanger. Er is geen per-ontvanger-variabele bij dit type. Zie Wat een klik rapporteert voor hoe je toch kliks kunt attribueren.
  • Geen tapsignaal, nooit. De tik op een linkbutton levert geen inbound bericht en geen webhook-event op. Bouw geen functie die klikstatistieken belooft op basis van alleen dit type.
  • Bird controleert de vorm van de URL, niet het scheme. url moet een absoluut adres met een scheme zijn, maar Bird vereist geen https, en Meta publiceert ook geen schemebeperking. Vergelijk dit met de url van een mediaheader, die gedocumenteerd is als vereist https.
  • Een mediaheader-URL die WhatsApp niet kan ophalen, faalt na acceptatie van de verzending. WhatsApp haalt het header-bestand op bij het versturen en cachet het 10 minuten; een gesigneerde URL moet langer geldig zijn dan de verzending, en een onbereikbare URL faalt asynchroon, met media_rejected op de last_error van het bericht.
Geen van de vormcontroles die de fouten-tabel van de hub opsomt kan bij dit type optreden: ze inspecteren de rijen van een lijst, een buttons-array of de kaarten van een carousel, en een cta_url-bericht heeft geen van de drie. Een vormfout, zoals een text-label van meer dan 20 tekens, komt terug als een generieke aanvraagvalidatiefout in plaats van een van die codes. Een citaat dat niet resolvet faalt het verzoek 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. Voor de fouten die elke WhatsApp-verzending kan tegenkomen, een gesloten venster, een ontbrekende of ongeldige afzender, of een ongeldige ontvanger, zie in de hub fouten en WhatsApp-berichten versturen.

Volgende stappen