Diese Seite wurde von der Cloud Translation API übersetzt.

Nachrichten empfangen

Nach der Registrierung bei Business Messages kannst du Nachrichten im Namen des Test-Agents empfangen. Sie können Nachrichten für Marken erhalten, die Sie verwalten, nachdem Sie Agents für diese Marken erstellen, bestätigen und starten.

Wenn ein Kunde eine Nachricht an einen von Ihnen verwalteten Agent sendet, sendet Business Messages eine JSON-Nutzlast an Ihren Webhook, der verschiedene IDs, Nachrichteninhalte und Standortinformationen enthält.

Verwenden Sie die Seite „Logs“ der Business Communications Developer Console, um Probleme bei der Nachrichtenzustellung zu beheben.

Eingehende Nachrichten verarbeiten

Wie Ihr Agent Nachrichten von Nutzern verarbeitet und antwortet, hängt stark von Ihrer Geschäftslogik ab. Im Allgemeinen sind die Schritte zum Beantworten einer Nutzernachricht jedoch konsistent.

Nachricht bestätigen

Um eine vom Webhook empfangene Nachricht zu bestätigen, geben Sie eine gültige HTTP-Antwort auf Nachrichten zurück, die an den Webhook gesendet werden.

Wenn eine Nachricht aufgrund von Zeitüberschreitungen bei der Zustellung, Webhook-Erreichbarkeit, Weiterleitung oder Berechtigungsproblemen nicht zugestellt wird, speichert und leitet Google die Nachricht mit mehreren Wiederholungsversuchen bis zu sieben Tage lang oder bis Ihr Webhook die Nachricht erfolgreich empfängt.

Überprüfen, ob die Nachricht von Google stammt

Sie sollten vor dem Verarbeiten des Nachrichteninhalts prüfen, ob Google die Nachricht gesendet hat.

So prüfen Sie, ob Google eine Nachricht gesendet hat:

Parsen Sie den X-Goog-Signature-Header der Nachricht. Dies ist eine gehashte, Base64-codierte Kopie der Nachrichtennutzlast.
Verwenden Sie das Clienttoken, das beim Konfigurieren des Webhooks als Schlüssel verwendet wurde, um einen SHA512-HMAC der Byte der Nachrichtennutzlast zu erstellen und das Ergebnis mit Base64 zu codieren.

Hinweis: Wenn Sie bei der Registrierung bei Business Messages einen Partnerschlüssel erhalten haben, verwenden Sie ihn als Schlüssel für den SHA512-HMAC anstelle des Clienttokens. Wenn Sie Ihren Webhook aktualisieren, verwenden Sie das Clienttoken für die Nachrichtenvalidierung mit der neuen Webhook-Konfiguration.
Vergleichen Sie den X-Goog-Signature-Hash mit dem von Ihnen erstellten Hash.
- Wenn die Hashes übereinstimmen, haben Sie bestätigt, dass die Nachricht von Google gesendet wurde.
- Wenn die Hashes nicht übereinstimmen, prüfen Sie Ihren Hash-Prozess bei einer als funktionierend bekannten Nachricht. Wenn der Hashing-Prozess korrekt funktioniert und Sie eine Nachricht erhalten, die Ihrer Meinung nach auf betrügerische Weise an Sie gesendet wurde, wenden Sie sich an uns. Sie müssen sich mit einem Google-Konto für Business Messages anmelden.

Ein Beispiel für die Nachrichtenüberprüfung finden Sie in den GitHub-Repositories für die Echo-Bots in Java, Node.js und Python.

Sprache ermitteln

Nutzer kommunizieren von vielen Orten und in vielen Sprachen. In Business Messages werden die Spracheinstellungen der Nutzer in den Feldern resolvedLocale und userDeviceLocale dargestellt, die auf den Spracheinstellungen der Geräte basieren. Weitere Informationen finden Sie unter Lokalisierung und Sprachen.

Wenn möglich, leiten Sie Nachrichten weiter und schreiben Sie Antworten basierend auf den Spracheinstellungen der Nutzer.

Nachricht basierend auf ihrem Kontext weiterleiten

Der Nachrichtenkontext gibt an, welche Art von Informationen der Nutzer möglicherweise sucht. Wenn ein Nutzer beispielsweise eine Nachricht mit einem placeId-Wert sendet, sendet er eine Nachricht an einen bestimmten Standort, der durch placeId identifiziert wird, und stellt wahrscheinlich standortspezifische Fragen. Wenn eine Nachricht einen nearPlaceId-Wert hat, der einen Standort in der Nähe des Nutzers angibt, möchte der Nutzer wahrscheinlich auch standortbezogene Informationen wissen. Der Agent sollte jedoch den Standort bestätigen, mit dem der Nutzer chatten möchte, bevor er die Unterhaltung beginnt.

Leiten Sie die Nachricht mit den Kontextinformationen der Nachricht an den Ort weiter, der am besten für die Antwort geeignet ist:

Wenn sich die Nachricht in einer neuen Unterhaltung befindet und eine häufig gestellte Frage gestellt wird, können Sie mit Automatisierung antworten.
Wenn die Frage nicht durch Automatisierung beantwortet werden kann, leiten Sie sie an einen Kundenservicemitarbeiter weiter.
Wenn die Sprache der Nachricht nicht mit der Standardsprache Ihres Agents übereinstimmt, leiten Sie die Nachricht an einen Live-Agent weiter, der diese Sprache unterstützt.
Wenn sich die Frage auf einen bestimmten Standort bezieht, leite ihn an jemanden mit Informationen zu diesem Ort weiter.
Wenn sich die Nachricht in einer laufenden Unterhaltung befindet, leiten Sie sie an den Kundenservicemitarbeiter weiter, der an der Unterhaltung teilnimmt.

Typ der gesendeten Nachricht

Nutzer können drei Arten von Nachrichten senden:

SMS sind Freitext-Antworten.
Image-Nachrichten enthalten eine signierte URL für ein Bild, das der Nutzer hochgeladen hat.
Vorschlagsnachrichten enthalten die Postback-Daten und den Text der vorgeschlagenen Aktion oder Antwortvorschläge, auf die der Nutzer getippt hat.

Nachrichteninhalt verarbeiten

Wenn der Agent Automatisierung verwendet, sollten der Inhalt der Nutzernachricht die Logik und die nächste Antwort des Agents in der Unterhaltung steuern.

Die Nutzerabsicht lässt sich am einfachsten mit Postback-Daten aus einer vorgeschlagenen Antwort oder einer vorgeschlagenen Aktion ermitteln. Unabhängig vom mit dem Vorschlag verknüpften Text sind die Postback-Daten maschinenlesbar.

Wenn ein Nutzer eine SMS sendet, kann der Agent die Antwort auf unterstützte Keywords parsen oder Natural Language Understanding (z. B. mit der Dialogflow-Integration) verwenden, um die Nachricht des Nutzers zu verarbeiten und einen Weg vorzuschlagen.

Wenn der Agent nicht weiß, wie er auf die Nachricht des Nutzers reagieren soll, sollte er mit einem Fehlerstatus reagieren und versuchen, die Unterhaltung fortzusetzen. Dazu fordert er den Nutzer auf, zusätzliche Informationen einzugeben, die Nachricht auf eine andere Weise einzugeben oder die Unterhaltung an einen Kundenservicemitarbeiter weiterzuleiten.

Dem Nutzer antworten

Nachdem der Agent die richtige Antwort identifiziert hat – entweder durch Automatisierung oder einen Live-Agent –, sendet er eine Nachricht und setzt die Unterhaltung mit dem Nutzer fort.

Berücksichtigen Sie beim Schreiben einer Antwort die Sprache des Nutzers. Sie können Antworten zusätzlich anpassen, indem Sie in jeder empfangenen Nachricht Werte vom Objekt userInfo abrufen.

Mitteilungstypen

Der folgende Code zeigt, wie der Agent Nachrichten empfängt.

Informationen zu Formatierung und Werten finden Sie unter UserMessage.

Text

Am häufigsten antworten Nutzer mit reinem Text. SMS haben das folgende Format.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "message": {
    "messageId": "MESSAGE_ID",
    "name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "text": "MESSAGE_TEXT",
    "createTime": "MESSAGE_CREATE_TIME",
  },
  "dialogflowResponse": {
    "autoResponded": "BOOLEAN",
    "faqResponse": {
      "userQuestion": "USER_QUESTION",
      "answers": [{
        "faqQuestion": "FAQ_QUESTION",
        "faqAnswer": "FAQ_ANSWER",
        "matchConfidenceLevel": "CONFIDENCE_LEVEL",
        "matchConfidence": "CONFIDENCE_NUMERIC",
      }],
    },
  },
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Formatierungs- und Wertoptionen finden Sie unter Message.

Bild

Nutzer können nicht nur Text senden, sondern auch Bilder als Nachrichten an Ihren Agent senden. Business Messages speichert geteilte Bilder 7 Tage unter signierte URLs und fügt diese URLs im Feld text der Nachrichtennutzlast ein.

Wenn der Agent Automatisierungen enthält, muss er in der Lage sein zu reagieren, wenn ein Nutzer ein Bild teilt. Achte bei Live-Agents darauf, dass die Bilder weitergeleitet werden oder dass die URLs in den Nachrichten anklickbar sind.

...
"message": {
    "text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
  }
...

Formatierungs- und Wertoptionen finden Sie unter Message.

Vorschlag

Vorgeschlagene Antworten und Aktionsvorschläge ermöglichen es Nutzern, mit nur einem Tippen zu reagieren oder Aktionen auszuführen. Wenn ein Nutzer auf einen Vorschlag tippt, empfängt der Agent eine Nutzlast mit Vorschlagstext und Postback-Daten.

Vorschlagsnachrichten haben das folgende Format.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "suggestionResponse": {
    "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "postbackData": "POSTBACK_DATA",
    "createTime": "RESPONSE_CREATE_TIME",
    "text": "SUGGESTION_TEXT",
    "suggestionType": "SUGGESTION_TYPE",
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Formatierungs- und Wertoptionen finden Sie unter SuggestionResponse.

Authentifizierungsanfrage

Mit dem Vorschlag für die Authentifizierungsanfrage können sich Nutzer bei einem OAuth-Anbieter anmelden, um Identitätsdetails mit dem Agent anzugeben oder dem Agent zu ermöglichen, im Namen des Nutzers Aktionen auszuführen. Weitere Informationen finden Sie unter Mit OAuth authentifizieren.

Wenn sich ein Nutzer erfolgreich beim angegebenen OAuth-Anbieter anmeldet, empfängt der Agent eine Nutzlast mit dem Autorisierungscode. Wenn ein Nutzer sich nicht anmelden kann, erhält der Agent eine Nutzlast mit Fehlerdetails.

Nachrichten zur Authentifizierungsanfrage haben das folgende Format.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "authenticationResponse": {
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "REDIRECT_URI",
    "errorDetails": {
      "error": "ERROR",
      "errorDescription": "ERROR_DESCRIPTION",
    },
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Formatierungs- und Wertoptionen finden Sie unter AuthenticationResponse.

Nachrichtenkontext

Jede Nachricht enthält Kontextinformationen zum Ursprung der Nachricht.

...
  "context": {
    "customContext": "CUSTOM_CONTEXT",
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
    "deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
    "widget": {
      "url": "WEBSITE_URL",
      "widgetContext": "WIDGET_CONTEXT",
    },
  },
...

Feld	Beschreibung
`customContext`	Kontextdaten, die vom Partner angegeben wurden.
`entryPoint`	Die Nachrichtenoberfläche, über die der Nutzer die Unterhaltung gestartet hat, wie durch EntryPoint definiert.
`placeId`	Eine eindeutige Kennung aus der Google Places-Datenbank für den Standort, an den der Nutzer eine Nachricht gesendet hat. Sie erscheint nur in Nachrichten von standortspezifischen Einstiegspunkten.
`nearPlaceId`	Eine eindeutige Kennung aus der Google Places-Datenbank für den ersten Standort in einem Local Pack. Bestätigen Sie die Standorte, mit denen Nutzer chatten möchten, wenn Sie `nearPlaceId`-Werte erhalten.
`deflectedPhoneNumber`	Die Telefonnummer, die Business Messages vom Nutzer abgewiesen hat, als die Unterhaltung gestartet wurde.
`resolvedLocale`	Die beste berechnete Sprache der Sprache des Nutzers (gemeldet in `userDeviceLocale`) und der vom Agent unterstützten Sprache (basierend auf den angegebenen Einstellungen für die Unterhaltung). Weitere Informationen finden Sie unter Lokalisierung und Unterhaltung starten. Das Gebietsschemawert ist ein wohlgeformtes IETF BCP 47-Sprach-Tag.
`userInfo.displayName`	Der Name des Nutzers, der die Nachricht gesendet hat. Wenn der Nutzer die Identitätsfreigabe deaktiviert, ist dieses Feld leer.
`userInfo.userDeviceLocale`	Die vom Nutzer gemeldete Sprache des Nutzers als korrekt formatiertes IETF BCP 47-Sprach-Tag
`widget.url`	Die URL der Website, auf der die dialogorientierte Oberfläche gestartet wurde.
`widget.widgetContext`	Der Attributwert `data-bm-widget-context` des Widgets, mit dem die Unterhaltung gestartet wird.

Unterhaltungsverlauf

Google stellt keinen Unterhaltungsverlauf zur Verfügung. Verwalten Sie Ihre bisherigen Unterhaltungen in einer Weise, die Ihrer Datenschutzerklärung und Ihren Best Practices entspricht. So können Sie zukünftige Antworten von Nutzern auf fundierte Entscheidungen rücken.