Cette page a été traduite par l'API Cloud Translation.

Recevoir des messages

Une fois que vous vous êtes inscrit avec 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 après avoir créé, validé et lancé les agents pour ces marques.

Lorsqu'un client envoie un message à un agent que vous gérez, Business Messages envoie une charge utile JSON contenant divers ID, contenus de message et informations de localisation.

Accédez à la page des journaux de la console de développement 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. Toutefois, la procédure à suivre pour répondre à un message utilisateur est généralement cohérente.

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 n'est pas distribué en raison d'un délai avant expiration, d'une accessibilité du webhook, d'une redirection ou d'un problème d'autorisation, Google le stocke et le transfère avec plusieurs tentatives pendant sept jours ou jusqu'à ce que le webhook reçoive le message.

Vérifier que le message provient de Google

Vous devez vérifier que Google a envoyé le message avant d'en traiter le contenu.

Pour vérifier que Google a bien envoyé un message,

Analysez l'en-tête X-Goog-Signature du message. Il s'agit d'une copie hachée, encodée en base64 de la charge utile du corps du message.
À l'aide de votre jeton client (présenté lorsque vous avez configuré votre webhook) comme clé, créez un HMAC SHA512 des octets de la charge utile du message, puis encodez le résultat en base64.

Remarque:Si vous avez reçu une clé partenaire lors de l'enregistrement auprès de Business Messages, utilisez-la comme clé HMAC SHA512 au lieu du jeton client. Si vous mettez à jour votre webhook, utilisez le jeton client pour valider les messages avec la nouvelle configuration du webhook.
Comparez le hachage X-Goog-Signature au hachage que vous avez créé.
- Si les hachages correspondent, vous avez confirmé que Google a envoyé le message.
- Si les hachages ne correspondent pas, vérifiez votre processus de hachage sur un message connu. Si votre processus de hachage fonctionne correctement et que vous recevez un message qui vous a été envoyé de manière frauduleuse, contactez-nous (vous devez vous connecter avec un compte Google Business Messages).

Consultez l'exemple de validation 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 endroits et dans de nombreuses langues. Business Messages représente les préférences linguistiques des utilisateurs avec les champs resolvedLocale et userDeviceLocale, qui sont basés sur les paramètres régionaux de leur appareil. Consultez Localisation et paramètres régionaux.

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

Router le message en fonction de son contexte

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

Avec les informations de contexte du message, routez-le vers l'emplacement le mieux adapté:

Si le message se trouve dans une nouvelle conversation et qu'il s'agit d'une question fréquente, vous pouvez répondre avec l'automatisation.
Si l'automatisation ne peut pas gérer la question, transmettez-la à un agent en direct.
Si les paramètres régionaux du message ne correspondent pas aux paramètres régionaux par défaut de l'agent, routez le message vers un agent en direct compatible avec cette langue.
Si la question concerne un lieu spécifique, transmettez-le à une personne disposant des informations sur ce lieu.
Si le message est dans une conversation en cours, routez-le vers l'agent en direct participant à la conversation.

Identifier le type de message envoyé par l'utilisateur

Les utilisateurs peuvent envoyer trois types de messages:

Les messages texte sont des réponses de forme libre.
Les messages de type Image incluent l'URL signée d'une image que l'utilisateur a importée.
Les messages de suggestion incluent les données de postback et le texte de l'action suggérée ou de 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 de l'utilisateur doit guider sa logique et sa prochaine réponse dans la conversation.

Le moyen le plus simple d'identifier l'intention d'un utilisateur consiste à utiliser les données de postback d'une suggestion ou d'une réponse. Quel que soit le 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 identifier les mots clés compatibles ou utiliser la compréhension du langage naturel (comme avec l'intégration Dialogflow pour traiter le message de l'utilisateur et identifier une procédure à 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 invitant l'utilisateur à fournir des informations supplémentaires, en demandant une entrée d'une autre manière ou en transmettant la conversation à un agent en direct.

Répondre à l'utilisateur

Une fois que l'agent a identifié la bonne réponse (via l'automatisation ou un agent actif), il envoie un 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 en savoir plus sur la mise en forme et les valeurs, consultez UserMessage.

Texte

Le moyen le plus courant pour répondre est d'utiliser du texte brut. Les SMS sont 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.

Images

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

Si votre agent inclut l'automatisation, assurez-vous qu'elle sache comment répondre si un utilisateur partage une image. Pour les agents en direct, assurez-vous que les images sont transmises ou que les URL des 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 les actions suggérées permettent aux utilisateurs de répondre ou d'effectuer des actions d'un simple geste. Lorsqu'un utilisateur appuie sur une suggestion, l'agent reçoit une charge utile contenant le texte de la suggestion et les données de postback.

Les messages de suggestion ont le format suivant :

{
  "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 fournisseur OAuth afin de fournir des informations d'identité à l'agent ou d'effectuer l'action pour le compte de l'utilisateur. Consultez la page S'authentifier avec OAuth.

Si un utilisateur se connecte au fournisseur OAuth spécifié, l'agent reçoit une charge utile avec le code d'autorisation. Si un utilisateur ne parvient pas à se connecter, l'agent reçoit une charge utile contenant des détails sur l'erreur.

Les messages de requête 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 démarré la conversation, telle que définie par EntryPoint.
`placeId`	Identifiant unique de la base de données Google Adresses pour l'établissement auquel l'utilisateur a envoyé un message. Elle n'apparaît que dans les messages provenant de points d'entrée spécifiques à un établissement.
`nearPlaceId`	Identifiant unique de la base de données Google Adresses pour le premier établissement d'un pack local. Confirmez les emplacements avec lesquels les utilisateurs souhaitent discuter lorsque vous recevez des valeurs `nearPlaceId`.
`deflectedPhoneNumber`	Numéro de téléphone que Business Messages a détourné de l'utilisateur au début de la conversation.
`resolvedLocale`	La meilleure correspondance calculée pour les paramètres régionaux de l'utilisateur (indiqués dans la section `userDeviceLocale`) et les paramètres régionaux compatibles avec l'agent (qui sont déterminés par les paramètres de conversation spécifiés). Consultez Localisation et lancez la conversation. La valeur des paramètres régionaux est une balise de langue IETF BCP 47 bien formatée.
`userInfo.displayName`	Nom de l'utilisateur qui a envoyé le message. Si l'utilisateur désactive le partage d'identité, ce champ est vide.
`userInfo.userDeviceLocale`	Paramètres régionaux de l'utilisateur, signalés par leur appareil, sous la forme d'une balise de langue IETF BCP 47 bien formatée.
`widget.url`	URL du site Web sur lequel la surface de conversation a été lancée.
`widget.widgetContext`	Valeur d'attribut `data-bm-widget-context` du widget utilisé pour démarrer la conversation.

Historique de la conversation

Google ne fournit pas d'historique des conversations. Conservez l'historique de vos conversations, tout en respectant vos règles de confidentialité et vos bonnes pratiques. Vous pourrez ainsi envoyer des réponses éclairées aux futurs messages des utilisateurs.