Recevoir des messages

Après vous être inscrit auprès de Business Messages vous pouvez recevoir des messages au nom de votre agent de test. Vous pouvez recevoir des messages pour les marques que vous gérez create, valider et lancement des agents de ces marques.

Lorsqu'un client envoie un message à un agent que vous gérez, Business Messages envoie à votre webhook une charge utile JSON contenant différents ID, le contenu du message et des informations de localisation.

Utiliser les journaux de la console pour les développeurs Business Communications pour déboguer les problèmes de distribution des messages.

Gérer les messages entrants

La manière dont votre agent traite les messages des utilisateurs et y répond dépend fortement de votre logique métier. En général, les étapes à suivre pour répondre à un utilisateur sont cohérents.

Confirmer le message

Pour accuser réception d'un message reçu par votre webhook, renvoyez une réponse HTTP valide aux messages envoyés à votre webhook.

Si un message échoue en raison du délai de distribution, de la joignabilité du webhook, les problèmes de redirection ou d'autorisation, Google stocke et transfère le message plusieurs tentatives pendant 7 jours ou jusqu'à ce que le webhook reçoive .

Vérifier que le message provient bien de Google

Vous devez vérifier que Google a envoyé le message avant de le traiter contenus.

Pour vérifier que Google a envoyé un message que vous avez reçu,

  1. Analyse l'en-tête X-Goog-Signature du message. Il s'agit d'une valeur hachée, de la charge utile du corps du message, encodée en base64.

  2. À l'aide de votre jeton client (présenté lors de la configuration de votre webhook) en tant que clé, créez un HMAC SHA512 des octets de la charge utile du message et Encodez le résultat en base64.

  3. Comparez le hachage X-Goog-Signature à celui que vous avez créé.

    • Si les hachages correspondent, vous avez confirmé que Google a envoyé le message.
    • Si les valeurs de hachage ne correspondent pas, vérifiez votre processus de hachage sur une propriété connue . Si votre processus de hachage fonctionne correctement et que vous recevez une qui vous a été envoyé de manière frauduleuse, nous contacter (vous devez signer dans avec un compte Google Business Messages).

Consultez l'exemple de vérification de message dans les dépôts GitHub pour les bots Echo. en Java, Node.js et Python.

Identifier les paramètres régionaux

Les utilisateurs communiquent depuis de nombreux pays et dans de nombreuses langues. Business Messages représente l'expérience utilisateur préférences linguistiques avec les resolvedLocale et Champs userDeviceLocale, basés sur les performances des appareils paramètres régionaux. Voir la section Localisation et paramètres régionaux.

Dans la mesure du possible, acheminez les messages et rédigez des réponses en fonction des besoins langue préférences.

Acheminer le message en fonction de son contexte

Le contexte du message permet de déterminer le type d'informations que l'utilisateur est susceptible de rechercher. Par exemple, si un utilisateur envoie un message avec placeId il a envoyé un message à un lieu spécifique (identifié par placeId) et susceptibles de poser des questions spécifiques au lieu. De même, si un message contient nearPlaceId, qui identifie un emplacement à proximité de l'utilisateur, celui-ci est probablement souhaite connaître des informations spécifiques au lieu, mais l'agent doit confirmer lieu avec lequel l'utilisateur souhaite discuter avant de démarrer la conversation.

Avec les informations contextuelles du message, acheminez-le vers l'emplacement le plus adapté adaptés pour répondre:

  • Si le message se trouve dans une nouvelle conversation et s'il s'agit d'une question fréquente, vous pouvez grâce à l'automatisation.
  • Si l'automatisation ne parvient pas à répondre à la question, transmettez-la à un agent.
  • Si les paramètres régionaux du message ne correspondent pas aux paramètres régionaux par défaut de votre agent, routez à un agent qui prend en charge ces paramètres régionaux.
  • Si la question concerne un lieu spécifique, transmettez-la à une personne ayant des informations sur ce lieu.
  • Si le message se trouve dans une conversation en cours, acheminez-le vers l'agent réel. participer à la conversation.

Identifier le type de message envoyé par l'utilisateur

Les utilisateurs peuvent envoyer trois types de messages:

  • Les SMS sont des réponses au format libre.
  • Les messages de type Image contiennent une URL signée pour une image que l'utilisateur importées.
  • Les messages de suggestion incluent les données de postback et le texte des l'action suggérée ou la réponse suggérée sur laquelle l'utilisateur a appuyé.

Traiter le contenu du message

Si votre agent utilise l'automatisation, le contenu du message utilisateur doit guider votre la logique de l'agent et la réponse suivante dans la conversation.

Le moyen le plus simple d'identifier l'intention de l'utilisateur est d'utiliser les données de postback d'une une suggestion de réponse ou d'action. Indépendamment du texte associé à la suggestion, les données de postback sont lisibles par un ordinateur.

Si un utilisateur envoie un SMS, votre agent peut analyser la réponse pour des mots clés pris en charge ou si vous utilisez la compréhension du langage naturel (par exemple, Dialogflow intégration pour traiter le message de l'utilisateur et identifier une voie à suivre.

Si votre agent ne sait pas comment répondre au message de l'utilisateur, il doit répondre avec un état d'erreur et essayer de poursuivre la conversation en en invitant l'utilisateur à fournir des informations supplémentaires, en lui demandant de saisir une d'une manière différente, ou en transmettant la conversation à un agent.

Répondre à l'utilisateur

Une fois que l'agent a identifié la bonne réponse, soit de façon automatisée, soit un agent réel qui envoie une message et poursuit la conversation avec l'utilisateur.

Lorsque vous rédigez une réponse, tenez compte des paramètres régionaux de l'utilisateur. Vous pouvez également personnaliser les réponses en récupérant des valeurs de l'objet userInfo dans chaque message que vous recevez.

Types de messages

Le code suivant montre comment votre agent reçoit les messages.

Pour obtenir des informations sur la mise en forme et les valeurs, consultez UserMessage

Texte

La façon la plus courante de répondre consiste à utiliser du texte brut. Les SMS contiennent au format suivant.

{
  "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",
}

Pour connaître les options de mise en forme et de valeur, consultez Message

Image

En plus d'envoyer du texte, les utilisateurs peuvent envoyer des images à votre agent sous forme de messages. Business Messages stocke les images partagées pendant sept jours à l'adresse URL et inclut ces URL dans le champ text de la charge utile du message.

Si votre agent inclut une automatisation, assurez-vous qu'elle sait comment répondre si un utilisateur partage une image. Pour les agents humains, assurez-vous que les images sont transmises ou que les URL dans les messages sont cliquables.

...
"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"
  }
...

Pour connaître les options de mise en forme et de valeur, consultez Message

Suggestion

Les réponses et actions suggérées permettent aux utilisateurs de répondre ou d'effectuer d'un simple geste. Lorsqu'un utilisateur appuie sur une suggestion, l'agent reçoit une charge utile avec le texte des suggestions et les données de postback.

Les messages de suggestion se présentent comme suit.

{
  "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",
}

Pour connaître les options de mise en forme et de valeur, consultez SuggestionResponse

Demande d'authentification

La suggestion de requête d'authentification permet aux utilisateurs de se connecter avec un de fournir des informations d'identité à l'agent ou de lui permettre d'effectuer des actions sur les données au nom de l'utilisateur. Consultez la section S'authentifier avec OAuth.

Si un utilisateur se connecte avec le fournisseur OAuth spécifié, l'agent reçoit une charge utile avec le code d'autorisation. Si un utilisateur ne parvient pas à lors de la connexion, l'agent reçoit une charge utile contenant les détails de l'erreur.

Les messages de demande d'authentification sont au format suivant.

{
  "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",
}

Pour connaître les options de mise en forme et de valeur, consultez AuthenticationResponse

Contexte du message

Chaque message contient des informations contextuelles sur son origine.

...
  "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",
    },
  },
...
Champ Description
customContext Données de contexte spécifiées par le partenaire.
entryPoint Surface de messagerie à partir de laquelle l'utilisateur a commencé la conversation, telle que définie par EntryPoint.
placeId Identifiant unique de l'emplacement issu de la base de données Google Places envoyé par l'utilisateur. Il apparaît uniquement dans les messages associés à un lieu spécifique. les points d'entrée.
nearPlaceId Un identifiant unique issu de la base de données Google Places pour le premier dans un pack local. Confirmer les établissements avec lesquels les utilisateurs souhaitent discuter lorsque vous recevez des valeurs nearPlaceId.
deflectedPhoneNumber Numéro de téléphone que l'utilisateur a refusé d'appeler à Business Messages quand la conversation a commencé.
resolvedLocale

La meilleure correspondance calculée pour les paramètres régionaux de l'utilisateur (indiquée dans userDeviceLocale) et les paramètres régionaux pris en charge par l'agent (déterminée par des paramètres de conversation spécifiés). Voir Localisation et Début la conversation.

La valeur des paramètres régionaux correspond à un tag de langue IETF BCP 47 valide.

userInfo.displayName Nom de l'utilisateur ayant envoyé le message. Si l'utilisateur désactive partage d'identité, ce champ est vide.
userInfo.userDeviceLocale Les paramètres régionaux de l'utilisateur, indiqués par l'appareil, sont au format Balise de langue IETF BCP 47.
widget.url URL du site Web sur lequel la surface de conversation a été lancée.
widget.widgetContext Le Valeur de l'attribut data-bm-widget-context du widget utilisé pour engager la conversation.

Historique de la conversation

Google ne fournit pas d'historique des conversations. Conservez votre propre historique tout en respectant vos règles de confidentialité et vos bonnes pratiques, afin que vous puissiez envoyer des réponses éclairées aux futurs messages des utilisateurs.