Cloud API

Unterhaltungskomponenten

Unterhaltungskomponenten sind Funktionen innerhalb eines Chats, die du für Unternehmenstelefonnummern aktivieren kannst. Sie erleichtern es WhatsApp-Benutzer*innen, mit deinem Unternehmen zu interagieren. Du kannst einfach zu verwendende Befehle konfigurieren, vorab erstellte Eisbrecher bereitstellen, auf die Benutzer*innen tippen können, und erstmaligen Benutzer*innen eine Begrüßungsnachricht senden.

Einschränkungen

Wenn ein*e WhatsApp-Benutzer*in auf einen universellen Link (d. h. einen wa.me-Link) tippt, der mit vorgefertigtem Text konfiguriert ist, werden die Benutzungsoberflächen für Eisbrecher automatisch verworfen.

Konfiguration über WhatsApp Manager (WAM)

Alle diese Features kannst du im WhatsApp Manager für die gewünschten Nummern konfigurieren:

  1. Navigiere zum Dashboard „Meine Apps“ auf der Website „Meta for Developers“.
  2. Wähle deine App aus und wählen anschließend im linken Bereich unter WhatsAppKonfiguration aus.
  3. Wähle unter Telefonnummern die Option Telefonnummern verwalten aus.
  4. Wähle rechts neben der Telefonnummer, die du konfigurieren möchtest, das Zahnrad-Symbol unter Einstellungen aus.
  5. Wähle Automatisierungen aus.
  6. Greife auf Unterhaltungskomponenten zu und konfiguriere diese.

Lösungspartner können diese Funktionen auch für ihre Kund*innen konfigurieren, wenn sie im WhatsApp Manager Zugriff auf das WhatsApp-Unternehmenskonto ihres*ihrer Kund*innen haben.

Begrüßungsnachrichten

Du kannst per Webhook benachrichtigt werden, wenn ein*e WhatsApp-Benutzer*in zum ersten Mal einen Chat mit dir eröffnet. Dies kann nützlich sein, wenn du diesen Benutzer*innen mit einer speziellen, selbstgestalteten Begrüßungsnachricht antworten möchtest.

Begrüßungsnachrichten eignen sich hervorragend für Dienstinteraktionen, z. B. beim Kund*innensupport oder bei der Kontodienstleistungen. Du kannst zum Beispiel einen WhatsApp-Button in deine App oder Website einbetten. Wenn Benutzer*innen auf den Button tippen, werden sie zu WhatsApp weitergeleitet, wo sie eine Begrüßungsnachricht erhalten, die Informationen dazu bereitstellt, wie sie mit dir interagieren können.

Wenn du diese Funktion aktivierst und dir ein*e Benutzer*in eine Nachricht sendet, prüft der WhatsApp-Client, ob es bereits einen Nachrichten-Thread zwischen dem*der Benutzer*in und deiner Unternehmenstelefonnummer gibt. Wenn es keinen gibt, löst der Client einen messages-Webhook aus, bei dem type auf request_welcome festgelegt ist. Du kannst dem*der Benutzer*in dann mit einer eigenen Begrüßungsnachricht antworten.

Der Webhook request_welcome löst ein Kund*innenservice-Zeitfenster aus, das es deinem Unternehmen ermöglicht, bei der Beantwortung von Kund*innenanfragen Freiformnachrichten zu senden.

Webhook-Payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "type": "request_welcome"  // Indicates first time message from WhatsApp user
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Eisbrecher

Eisbrecher sind anpassbare, antippbare Text-Strings, die in einem Nachrichtenthread angezeigt werden, wenn du zum ersten Mal mit einem*einer Benutzer*in chattest. Zum Beispiel „Eine Reise planen“ oder „Einen Trainingsplan erstellen“.

Eisbrecher eignen sich hervorragend für Dienstinteraktionen, beispielsweise für den Kund*innensupport oder Kontodienstleistungen. Du kannst zum Beispiel einen WhatsApp-Button in deine App oder Website einbetten. Wenn Benutzer*innen auf den Button tippen, werden sie zu WhatsApp weitergeleitet, wo sie aus einer Reihe anpassbarer Aufforderungen auswählen können, die ihnen zeigen, wie sie mit deinen Diensten interagieren können.

Du kannst bis zu vier Eisbrecher für eine Unternehmenstelefonnummer konfigurieren. Jeder Eisbrecher kann jeweils bis zu 80 Zeichen lang sein. Emojis werden nicht unterstützt.

Wenn ein*e Benutzer*in auf einen Eisbrecher tippt, wird ein Standard-Webhook für empfangene Nachrichten ausgelöst. Hierbei wird der Eisbrecher-String der Eigenschaft body in der Payload zugewiesen. Wenn der*die Benutzer*in versucht, dir eine Nachricht zu senden, anstatt auf einen Eisbrecher zu tippen, wird die Tastatur als Overlay angezeigt. Sie kann jedoch ausgeblendet werden, um das Eisbrecher-Menü erneut anzuzeigen.

Wenn ein*e WhatsApp-Benutzer*in auf einen universellen Link (wa.me- oder api.whatsapp.com-Link) tippt, der mit vorgefertigtem Text konfiguriert ist, werden die Benutzungsoberflächen für Eisbrecher automatisch verworfen.

Webhook-Payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "text": {
                  "body": "Plan a trip"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Befehle

Befehle sind Text-Strings, die WhatsApp-Benutzer*innen anzeigen können, indem sie einen Schrägstrich in einem Nachrichten-Thread mit deinem Unternehmen eingeben.

Befehle bestehen aus dem Befehl selbst und einem Hinweis, der dem*der Benutzer*in zeigt, was passieren kann, wenn er*sie den Befehl verwendet. Du kannst den Befehl beispielsweise folgendermaßen definieren:

/imagine - Create images using a text prompt

Wenn ein*e WhatsApp-Benutzer*in /imagine Autorennen auf dem Mars eingibt, wird ein Webhook für empfangene Nachrichten mit genau diesem Text-String ausgelöst, welcher der Eigenschaft body zugewiesen ist. Du kannst dann beispielsweise ein Bild von Autos, die auf dem Planeten Mars ein Rennen fahren, generieren und zurückgeben.

Du kannst bis zu 30 Befehle definieren. Jeder Befehl beinhaltet maximal 32 Zeichen und jeder Hinweis maximal 256 Zeichen. Emojis werden nicht unterstützt.

Webhook-Payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "text": {
                  "body": "/imagine cars racing on Mars"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Konfiguration über die API

Mit der API kannst du auch Unterhaltungskomponenten konfigurieren und alle konfigurierten Werte anzeigen.

Die Conversational Components API verfügt über zwei Endpunkte:

Mit POST </PHONE_NUMBER_ID>/conversational_automation werden Unterhaltungskomponenten für eine bestimmte Telefonnummer konfiguriert.

GET /<PHONE_NUMBER_ID>/conversational_automation gibt die aktuellen Werte für die Felder „enable_welcome_message“, „commands“ und „prompts“ für eine bestimmte Telefonnummer zurück.

Konfiguration von Unterhaltungskomponenten über die API

Du kannst Unterhaltungskomponenten für eine bestimmte Telefonnummer konfigurieren, indem du den POST-Endpunkt aufrufst.

Anfragesyntax

// Enable or disable the Welcome Message for the given phone number ID
POST /<PHONE_NUMBER_ID>/conversational_automation?enable_welcome_message=<ENABLE_DISABLE>

// Configure Commands with names and descriptions
POST /<PHONE_NUMBER_ID>/conversational_automation?commands=<COMMAND_LIST>

// Configure Prompts
POST /<PHONE_NUMBER_ID>/conversational_automation?prompts=<PROMPT>

Texteigenschaften


PlatzhalterBeschreibungBeispielwert

<PHONE_NUMBER_ID>

Integer

Erforderlich.


Eine Telefonnummer-ID auf einem WhatsApp-Unternehmenskonto

+12784358810

<ENABLE_DISABLE>

Boolesch

Optional.


Ein boolescher Wert zum Aktivieren oder Deaktivieren einer Begrüßungsnachricht für die Telefonnummer


true

<COMMAND_LIST>

JSON

Optional.


Eine Liste von Befehlen, die konfiguriert werden sollen


"commands": {
     "command_name": "generate"
     "command_description": "Create a new image",
     “command_name”: “rethink”
     “command_description”: “Generate new images from existing images”,
}

<PROMPTS>

Liste von Strings

Optional.


Die Aufforderung(en), die konfiguriert werden soll(en).


"prompts": ["Book a flight","plan a vacation"]

Beispielanfrage

   curl -X POST \
 'https://graph.facebook.com/v19.0/PHONE_NUMBER_ID/conversational_automation' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "enable_welcome_message": true/false,
   "commands": [
     {
       "command_name": "tickets",
       "command_description": "Book flight tickets",
     },
     {
       "command_name": "hotel",
       "command_description": "Book hotel",
     }
   ],
 "prompts": ["Book a flight","plan a vacation"]
}'

Beispielantwort

{
  "success": true
}

Aktuelle Konfiguration über die API anzeigen

Du kannst die aktuelle Konfiguration von Conversational Components für eine bestimmte Telefonnummer anzeigen, indem du den GET-Endpunkt aufrufst.

Anfragesyntax

GET  /<PHONE_NUMBER_ID>?fields=conversational_automation

Beispielantwort

{
  "conversational_automation": {
    "enable_welcome_message": true
    "prompts": [
      "Find the best hotels in the area",
      "Find deals on rental cars"
    ],
    "commands": [
      {
        "command_name": "tickets",
        "command_description": "Book flight tickets",
      },
      {
        "command_name": "hotel",
        "command_description": "Book hotel",
      }
    ],
  }
  "id": "123456"
}

Testen

Um fertig konfigurierte Unterhaltungskomponenten zu testen, öffne den WhatsApp-Client und öffne einen Chat mit deiner Unternehmenstelefonnummer.

Wenn du bereits einen Chat-Thread mit der Unternehmenstelefonnummer hast und du die Begrüßungsnachrichten und Eisbrecher testen möchtest, musst du zuerst den Chat-Thread löschen:

  1. Öffne den Thread im WhatsApp-Client.
  2. Tippe auf das Profil der Unternehmenstelefonnummer.
  3. Tippe auf Chat leeren > Alle Nachrichten löschen.
  4. Chat löschen.
  5. Starte einen neuen Chat-Thread mit diesem Unternehmen.

Du kannst dann eine Nachricht an die Unternehmenstelefonnummer senden, wodurch der request_welcome-Webhook ausgelöst werden sollte.