Arbeiten mit interaktiven WhatsApp-Nachrichten
Interaktive Nachrichten sind eine Funktion von WhatsApp für Unternehmen. Die Vonage Messages API ermöglicht es Ihnen, diese Funktion durch die Verwendung seiner API-Endpunkte und Webhooks zu nutzen.
Grundlegender Ablauf einer Applikation
Der grundlegende Ablauf für die Arbeit mit interaktiven WhatsApp-Nachrichten ist wie folgt:
Senden Sie eine
POSTAnfrage an den/v1/messagesEndpunkt. Der Anfragekörper sollte die erforderlichen JSON-Daten enthalten, wobei diechanneleingestellt aufwhatsappund diemessage_typeeingestellt aufcustom. DiecustomFeld muss mit einem entsprechend formatierten benutzerdefiniertes Objekt. Die tatsächliche Struktur des benutzerdefinierten Objekts hängt von der Art der gesendeten interaktiven Nachricht ab (z. B. Antwortschaltfläche oder Liste).Der entsprechende Nachrichtentyp wird dann im angegebenen WhatsApp-Chat wiedergegeben. Der Kunde kann mit der Nachricht interagieren, z. B. auf eine Antwort-Schaltfläche klicken oder eine Option aus einer Liste auswählen (je nach Nachrichtentyp). Die Vonage Messages API informiert Sie dann über diese Interaktion durch einen Rückruf mit der Nutzlast der Nachricht unter Verwendung eines vorkonfigurierten Webhaken für eingehende Nachrichten
Auf der Grundlage des Inhalts der über den Callback empfangenen Nutzlast können Sie beliebige Aktionen durchführen, wie z. B. das Senden einer weiteren Anfrage.
HINWEIS: Der Webhook für eingehende Nachrichten zum Empfang der Rückrufe muss als Teil eines Vonage Anwendung
Einrichten Ihrer Applikation
Sie können Ihre Vonage-Applikation auf verschiedene Weise einrichten, z. B. über die Dashboardüber einen Aufruf der Applications API oder über die Vonage CLI. Im Folgenden wird die Einrichtung einer Anwendung über das Dashboard beschrieben.
- Erstellen Sie eine neue Anwendung unter Ihre Applications (geben Sie ihr einen passenden Namen, etc.)
- Aktivieren Sie unter Funktionen die Option Nachrichten
- Die Aktivierung von Nachrichten sollte Felder für eingehende und Status-Webhooks freilegen. Setzen Sie den eingehenden Webhook auf die URL, unter der Sie die Rückrufe für die interaktiven WhatsApp-Nachrichten empfangen möchten.
- Setzen Sie die Messages API-Version über das Dropdown-Menü auf v1
- Klicken Sie auf Neue Anwendung generieren
- Sobald die Anwendung erstellt ist, wird eine Registerkarte "Soziale Kanäle verknüpfen" angezeigt. Unter dieser Registerkarte können Sie Ihre WhatsApp Business-Nummer verknüpfen
HINWEIS: Vonage Applications schreibt die Verwendung von JWT (JSON Web Tokens) zur Authentifizierung von Anfragen an die API vor, d. h. HTTP Basic Authentication ist keine Option, wenn Messages API v1 mit Webhooks verwendet wird. Lesen Sie mehr über JWTs.
Interaktive Botschaften: Beispiele
Die Struktur des JSON-Objekts variiert je nach Art der interaktiven Nachricht und auch von Nachricht zu Nachricht. Als Standard müssen Sie jedoch die from und to Numbers, a channel Taste eingestellt auf whatsappund eine message_type von custom. Sie müssen dann eine custom Schlüssel, dessen Wert ein benutzerdefiniertes Objekt. Das benutzerdefinierte Objekt sollte eine type Taste von interactiveund ein interactive Schlüssel, dessen Wert selbst ein Objekt ist.
Die interactive Objekt definiert die interaktive Nachricht. Es sollte eine type Taste entweder auf button oder listund besteht im Allgemeinen aus vier Hauptteilen: header, body, footerund action. Die action bestimmt die interaktiven Elemente innerhalb der Nachricht, wie z. B. Schaltflächen oder Listenoptionen.
Antwort-Schaltflächen: Beispiel
Hier ein Beispiel für den Textkörper einer Anfrage zum Senden einer interaktiven WhatsApp-Nachricht mit drei Antwortschaltflächen:
"from": "YOUR_WABA_NUMBER",
"to": "USERS_NUMBER",
"channel": "whatsapp",
"message_type": "custom",
"custom": {
"type": "interactive",
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "Delivery time"
},
"body": {
"text": "Which time would you like us to deliver your order at?"
},
"footer": {
"text": "Please allow 15 mins either side of your chosen time"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "slot-1",
"title": "15:00"
}
},
{
"type": "reply",
"reply": {
"id": "slot-2",
"title": "16:30"
}
},
{
"type": "reply",
"reply": {
"id": "slot-3",
"title": "17:15"
}
}
]
}
}
}
}
Die resultierende Meldung sieht wie folgt aus:
In der WhatsApp-Benutzeroberfläche ändert die Nachricht ihr Aussehen, als ob der Benutzer auf diese Nachricht mit dem Text einer der Schaltflächen geantwortet hätte. Außerdem wird diese Schaltfläche nicht mehr anklickbar, während die anderen anklickbar bleiben.
Wenn der Benutzer die erste Option auswählt, würden Sie anschließend über den eingehenden Webhook etwas wie dieses erhalten:
{
"to": "YOUR_WABA_NUMBER",
"from": "USERS_NUMBER",
"channel": "whatsapp",
"message_uuid": "00000000-0000-0000-0000-000000000000",
"timestamp": "2021-08-10T00:00:00Z",
"message_type": "reply",
"reply": {
"id": "slot-1",
"title": "15:00"
}
}
Meldungen auflisten: Beispiel
Hier ist ein Beispiel für den Text einer Anfrage zum Senden einer interaktiven WhatsApp-Listennachricht mit vier Optionen, die in zwei Abschnitte unterteilt sind:
"from": "YOUR_WABA_NUMBER",
"to": "USERS_NUMBER",
"channel": "whatsapp",
"message_type": "custom",
"custom": {
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "Select which pill you would like "
},
"body": {
"text": "You will be presented with a list of options"
},
"footer": {
"text": "There are no wrong choices"
},
"action": {
"button": "Select",
"sections": [
{
"title": "Section A - pills",
"rows": [
{
"id": "row1",
"title": "Red",
"description": "Take the red pill"
},
{
"id": "row2",
"title": "Blue",
"description": "Take the blue pill"
},
{
"id": "row3",
"title": "Green",
"description": "Take the green pill"
}
]
},
{
"title": "Section B - no pills",
"rows": [
{
"id": "row4",
"title": "Nothing",
"description": "Do not take a pill"
}
]
}
]
}
}
}
}
Die resultierende Meldung sieht wie folgt aus:
Wenn der Benutzer auf die Schaltfläche "Auswählen" klickt, werden die verfügbaren Optionen angezeigt. Dann kann der Benutzer eine Option (maximal) auswählen und auf die Schaltfläche "Senden" klicken.
Das Aussehen der Nachricht ändert sich so, als ob der Benutzer auf die Nachricht mit dem Text aus den Feldern Titel und Beschreibung der API-Anforderung geantwortet hätte.
Wenn der Kunde die erste Option aus Abschnitt A gewählt hat, würden Sie anschließend über den eingehenden Webhook etwa Folgendes erhalten:
{
"to": "YOUR_WABA_NUMBER",
"from": "USERS_NUMBER",
"channel": "whatsapp",
"message_uuid": "00000000-0000-0000-0000-000000000000",
"timestamp": "2021-08-10T00:00:00Z",
"message_type": "reply",
"reply": {
"id": "row1",
"title": "Red",
"description": "Take the red pill"
}
}