Senden von interaktiven Nachrichtenvorlagen
Mit interaktiven Nachrichtenvorlagen kannst du mehr Inhalte an Empfänger*innen senden, die über die Inhalte von Standard- und Medien-Nachrichtenvorlagen hinausgehen, nämlich interaktive Buttons. Hierzu verwendest du das Objekt components.
Es werden zwei Arten von vordefinierten Buttons angeboten:
- Call-to-Action: Damit können deine Kund*innen eine Telefonnummer anrufen und eine Website besuchen.
- Schnellantwort: Damit können deine Kund*innen eine einfache Textnachricht zurückgeben.
Diese Buttons können an Textnachrichten oder Mediennachrichten angehängt werden. Sobald deine interaktiven Nachrichtenvorlagen erstellt und genehmigt wurden, kannst du sie in Benachrichtigungsnachrichten sowie in Kundenservice-Nachrichten verwenden.
Bevor du beginnst
Voraussetzungen:
- Du musst alle im Abschnitt Bevor du beginnst der Nachrichten-Dokumentation aufgeführten Voraussetzungen erfüllen.
- Du musst eine interaktive Nachrichtenvorlage in Business Manager erstellen. Du kannst entweder einen Call-to-Action-Button oder einen Schnellantwort-Button hinzufügen.
Sobald die Nachrichtenvorlage genehmigt wurde, kannst du die API zum Senden einer Nachricht verwenden.
Einschränkungen
- Du kannst zwei Buttons zu Call-to-Action-Vorlagen hinzufügen, jeweils maximal einen Button jedes Typs (Telefonnummer anrufen und Website besuchen).
- Zu Schnellantwortvorlagen kannst du bis zu drei Buttons hinzufügen.
Schritt 1: POST-Anfrage an /messages senden
POST /v1/messages
{
"to": "recipient_wa_id",
"type": "template",
"template": {
"namespace": "your-namespace",
"language": {
"policy": "deterministic",
"code": "your-language-and-locale-code"
},
"name": "your-template-name",
"components": [
{
"type" : "header",
"parameters": [
{
"type": "text",
"text": "replacement_text"
}
]
# end header
},
{
"type" : "body",
"parameters": [
{
"type": "text",
"text": "replacement_text"
},
{
"type": "currency",
"currency" : {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33, #OR
"timestamp": 1485470276
}
},
{
...
# Any additional template parameters
}
]
# end body
},
# The following part of this code example includes several possible button types,
# not all are required for an interactive message template API call.
{
"type": "button",
"sub_type" : "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
# Business Developer-defined payload
"payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "1",
"parameters": [
{
"type": "text",
# Business Developer-defined dynamic URL suffix
"text": "9rwnB8RbYmPF5t2Mn09x4h"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "2",
"parameters": [
{
"type": "text",
# Business Developer-defined dynamic URL suffix
"text": "ticket.pdf"
}
]
}
]
}
}
Parameter
- Parameter für Nachrichtenvorlagen:
componentsObjekt: Binde für interaktive Nachrichtenvorlagen denbutton-Typ und dassub_type-Feld ein.
Schritt 2: API-Antwort prüfen
Eine erfolgreiche Antwort beinhaltet ein messages-Objekt mit einer id.
{
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Wenn der Vorgang fehlschlägt, enthält die Antwort ein Fehlerobjekt, das eine Fehlerzeichenfolge, einen Fehlercode und andere Informationen umfasst.
Wenn eine Vorlage an ein Konto gesendet wird, das die Vorlage nicht empfangen kann, wird der Fehler 1026 (ReceiverIncapable) im Fehlerobjekt an den konfigurierten Webhook-Server gesendet.
Weitere Informationen zu Fehlern findest du unter Fehler- und Statuscodes.
Optionaler Schritt 3: Aktionen von Nutzer*innen handhaben
Wenn ein*e Nutzer*in auf einen Schnellantwort-Button klickt, wird eine Antwort an das Unternehmen gesendet. Informationen dazu findest du unter Rückruf per Klick auf Schnellantwort-Button. Nutzer*innen können auch entscheiden, nicht auf den Button zu klicken und dir stattdessen eine Freitextnachricht zu senden.
Rückruf per Klick auf Schnellantwort-Button
{
"contacts": [
{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16505551234"
}
],
"messages": [
{
"button": {
"payload": "No-Button-Payload",
"text": "No"
},
"context": {
"from": "16315558007",
"id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
},
"from": "16505551234",
"id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
"timestamp": "1591210827",
"type": "button"
}
]
# If there are any errors, an errors field (array) will be present
"errors": [ { ... } ]
}
Beispiele
In diesen Beispielen wird demonstriert, wie interaktive Nachrichtenvorlagen eingerichtet werden. Am Anfang stehen die Vorlagenerstellung in deinem Business Manager und das Senden der Nachrichtenvorlagen mit API-Aufrufen an den messages-Endpunkt.
Reiseerinnerung
Dieses Beispiel zeigt die Erstellung einer interaktiven Medien-Nachrichtenvorlage mit Schnellantwort-Buttons.
1. Erstelle die interaktive Medien-Nachrichtenvorlage in deinem Business Manager.
2. Der messages-API-Aufruf fügt die Parameterinformationen ein.
POST /v1/messages
{
"to": "your-test-recipient-wa-id",
"recipient_type": "individual",
"type": "template",
"template": {
"namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
"name": "upcoming_trip_reminder",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "text",
"text": "12/26"
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "*Ski Trip*"
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "29th July 2019, 8:00am",
"day_of_month": "29",
"year": "2019",
"month": "7",
"hour": "8",
"minute": "00"
}
},
{
"type": "text",
"text": "*Squaw Valley Ski Resort, Tahoe*"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 0,
"parameters": [
{
"type": "payload",
"payload": "Yes-Button-Payload"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 1,
"parameters": [
{
"type": "payload",
"payload": "No-Button-Payload"
}
]
}
]
}
}
3. Deine Kund*innen erhalten ihre Reiseerinnerungsnachricht mit Schnellantwort-Buttons.
Produktversand
Dieses Beispiel zeigt die Erstellung einer interaktiven Medien-Nachrichtenvorlage mit URL- und Telefonanruf-Buttons.
1. Erstelle die interaktive Medien-Nachrichtenvorlage in deinem Business Manager.
2. Der messages-API-Aufruf fügt die Parameterinformationen ein.
POST /v1/messages
{
"to": "your-test-recipient-wa-id",
"recipient_type": "individual",
"type": "template",
"template": {
"namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
"name": "oculus_shipment_update",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [{
"type": "image",
"image": {
"link": "link-to-your-image"
}
}]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Anand"
},
{
"type": "text",
"text": "Quest"
},
{
"type": "text",
"text": "113-0921387"
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "23rd Nov 2019",
"day_of_month": "20",
"year": "2019",
"month": "9"
}
}
]
},
{
"type": "button",
"index": "0",
"sub_type": "url",
"parameters": [
{
"type": "text",
"text": "1Z999AA10123456784"
}
]
}
]
}
}
3. Dein*e Kund*innen erhalten ihre Produktversandbenachrichtigung mit URL- und Telefonanruf-Buttons.
