WhatsApp-Link-Buttons
Ein Link-Button platziert einen antippbaren Button unter einer WhatsApp-Nachricht, der eine URL im Browser des Empfängers öffnet. Verwenden Sie ihn, wenn der nächste Schritt im Web liegt, etwa eine Checkout-Seite oder eine Liste von Workshop-Terminen, und nicht im Chat selbst. Für eine Auswahl, die der Empfänger innerhalb von WhatsApp beantwortet, verwenden Sie stattdessen Antwort-Buttons oder Listenmenüs.
Einen Link-Button senden
Setzen Sie interactive.type auf cta_url mit einem body_text- und einem cta_url-Objekt, das text und url des Buttons enthält:
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);msg = client.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"},
},
)
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: "+16505551234",
From: "+13124495648",
Interactive: &bird.WhatsAppInteractiveSend{
Type: "cta_url",
BodyText: "Tap the button below to see the available dates.",
CtaUrl: &bird.WhatsAppInteractiveCtaUrlSend{Text: "See dates", Url: "https://example.com/workshops?click_id=a1b2c3"},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$interactive = (new WhatsAppMessageSendRequestInteractive())
->setType('cta_url')
->setBodyText('Tap the button below to see the available dates.')
->setCtaUrl(
(new WhatsAppInteractiveSendCtaUrl())
->setText('See dates')
->setUrl('https://example.com/workshops?click_id=a1b2c3'),
);
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--interactive '{"body_text":"Tap the button below to see the available dates.","cta_url":{"text":"See dates","url":"https://example.com/workshops?click_id=a1b2c3"},"type":"cta_url"}' \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"interactive": {
"body_text": "Tap the button below to see the available dates.",
"cta_url": {
"text": "See dates",
"url": "https://example.com/workshops?click_id=a1b2c3"
},
"type": "cta_url"
},
"to": "+16505551234"
}
}curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}
}'from ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete. Die vollständige Struktur fügt einen optionalen Header, Footer und ein Zitat einer früheren Nachricht hinzu:
Codebeispiel
{
"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 zitiert eine frühere Nachricht in derselben Konversation. Unter Nachricht zitieren, um eine Antwort zuzuordnen im Hub erfahren Sie, wie die Auflösung funktioniert und was sie übersehen kann.
Dieser Typ sendet genau einen cta_url-Button und kann buttons, list oder cards nicht zusätzlich enthalten. Im Abschnitt Buttons des Hubs finden Sie die gemeinsame Button-Struktur, die auch der Link-Button einer Karussell-Karte wiederverwendet.
Header und Footer
Ein Header ist optional und hat eine von vier Formen:
Codebeispiel
"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" }Ein Media-Header (image, video oder document) übergibt seine Datei als öffentliche https-URL, die WhatsApp beim Senden abruft, statt als hochgeladenes Media-Handle. footer_text ist optional und fügt eine Zeile unter dem Button hinzu.
Grenzen
| Feld | Grenze |
|---|---|
| cta_url-Buttons | genau einer |
| cta_url.text (Label) | erforderlich, 1 bis 20 Zeichen |
| cta_url.url | erforderlich, 1 bis 2.000 Zeichen |
| body_text | erforderlich, 1 bis 1.024 Zeichen |
| footer_text | optional, 1 bis 60 Zeichen |
| header.text | 1 bis 60 Zeichen |
Die 2.000-Zeichen-Grenze für url stammt von Bird: Meta veröffentlicht kein Längenlimit für dieses Feld. url prüft außerdem format: uri, eine absolute Adresse mit Schema, aber Bird prüft nicht, welches Schema: Eine http://-Adresse besteht die Validierung von Bird, und Meta ist die einzige Instanz, die entscheidet, ob sie zugestellt wird.
Was ein Klick zurückmeldet
Ein Tippen öffnet die Adresse im Browser des Empfängers, und über die API kommt nichts an Sie zurück. Das Tippen auf einen Link-Button ist kein interactive_reply: Der Inbound-Mapper, der interactive_reply erzeugt, verarbeitet nur das Tippen auf einen Antwort-Button und eine Listenzeile, und ein cta_url-Link hat keine entsprechende Inbound-Struktur. Was Sie sehen, ist der normale ausgehende Lebenszyklus – die Statusmeldungen sent, delivered und read der Nachricht –, aber read_at sagt Ihnen, dass die Nachricht geöffnet wurde, nicht dass der Button angetippt wurde. Es gibt kein Klick-Event, keinen Zeitstempel und kein empfängerspezifisches Tipp-Signal von WhatsApp oder von Bird.
Zwei Wege, um eine Zuordnung zu erhalten, da der Versand selbst sie Ihnen nicht liefert:
- Instrumentieren Sie die Zielseite. Der einzige verfügbare Klicknachweis liegt auf Ihrem eigenen Zielserver, anhand der URL, die Sie ausgegeben haben.
- Variieren Sie die URL selbst, pro Empfänger. Die url, die Sie senden, ist ein Literal-String: Bird speichert sie und gibt sie unverändert an Meta weiter, ohne Ersetzung und ohne Variablensyntax. Sie ist für jeden Empfänger eines Versands identisch. Empfängerspezifische Zuordnung bedeutet daher, einen eigenen Query-Parameter zu erzeugen, etwa ?click_id=<value>, und pro Empfänger einen POST /v1/whatsapp/messages-Aufruf auszuführen. Der Endpunkt nimmt bereits einen einzelnen to pro Aufruf entgegen, sodass dies Buchhaltung auf Ihrer Seite ist und kein fehlendes API-Feature.
Eine dritte Option liegt ganz außerhalb dieses Typs: Ein Template mit einer url-Button-Variable wird von WhatsApp selbst pro Empfänger personalisiert, bereitgestellt über die button-Komponente des Versands. Diese Variable muss am Ende der Adresse stehen, geschrieben als {{1}}, sodass sie ein abschließendes Pfadsegment oder einen Query-Wert variieren kann, aber niemals den Host oder die Mitte der URL. Der Kompromiss: Ein Template bietet empfängerspezifische URLs und Zustellung außerhalb des Kundenservice-Fensters, erfordert aber Metas Review und eine feste genehmigte Struktur. Ein cta_url-Versand bietet dagegen freiformatigen, reviewfreien Versand innerhalb eines offenen Fensters mit einer URL, die Sie selbst variieren.
Grenzen und Sonderfälle
- Das Kundenservice-Fenster muss offen sein. Ein Link-Button ist eine Service-Nachricht und kann nur innerhalb eines offenen Fensters zugestellt werden; siehe Kundenservice-Fenster im Hub. Die Fensterprüfung schlägt offen fehl, sodass ein 202 kein Beweis dafür ist, dass das Fenster beim Versand tatsächlich offen war.
- from muss eine Nummer sein, die Ihr Workspace besitzt. Wird sie weggelassen oder eine Nummer angegeben, die kein verbundener Sender ist, wird der Versand vor der Erstellung abgelehnt.
- Die URL ist für den gesamten Versand statisch und für jeden Empfänger identisch. Es gibt keine empfängerspezifische Variable bei diesem Typ. Siehe Was ein Klick zurückmeldet für Möglichkeiten, Klicks dennoch zuzuordnen.
- Kein Tipp-Signal, niemals. Das Tippen auf einen Link-Button erzeugt keine Inbound-Nachricht und kein Webhook-Event. Bauen Sie kein Feature, das Klickmetriken allein von diesem Typ verspricht.
- Bird prüft die Form der URL, nicht ihr Schema. url muss eine absolute Adresse mit Schema sein, aber Bird verlangt kein https, und Meta veröffentlicht ebenfalls keine Schema-Einschränkung. Vergleichen Sie das mit url eines Media-Headers, für das https dokumentiert als erforderlich ist.
- Eine Media-Header-URL, die WhatsApp nicht abrufen kann, schlägt nach Annahme des Versands fehl. WhatsApp ruft das Header-Asset beim Senden ab und cacht es 10 Minuten lang; eine signierte URL muss den Versand überdauern, und eine nicht erreichbare URL schlägt asynchron fehl, mit media_rejected im last_error der Nachricht.
Keine der Strukturprüfungen, die die Fehlertabelle des Hubs auflistet, kann bei diesem Typ ausgelöst werden: Sie prüfen die Zeilen einer Liste, ein buttons-Array oder die Karten eines Karussells, und eine cta_url-Nachricht hat keine dieser drei Strukturen. Ein Formfehler, etwa ein text-Label mit mehr als 20 Zeichen, wird als generischer Request-Validierungsfehler zurückgegeben und nicht als einer dieser Codes. Ein Zitat, das sich nicht auflösen lässt, lässt den Request fehlschlagen, bevor etwas erstellt oder berechnet wird: 404 E15071, wenn die ID keine Nachricht benennt, die dieser Workspace besitzt, 422 E15072, wenn sie eine benennt, die nicht zitiert werden kann. Für Fehler, die jeder WhatsApp-Versand auslösen kann – ein geschlossenes Fenster, ein fehlender oder ungültiger Sender oder ein ungültiger Empfänger –, siehe Fehler und WhatsApp-Nachrichten senden im Hub.
Nächste Schritte
- Interaktive WhatsApp-Nachrichten: was alle sechs interaktiven Typen gemeinsam haben
- WhatsApp-Templates: für eine url-Button-Variable, die WhatsApp pro Empfänger personalisiert
- WhatsApp-Nachrichten senden: der Request-Envelope, das 202-Modell und sicheres erneutes Versuchen
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten