接收消息

注册 Business Messages 后，您可以代表测试代理接收消息。您可以在为这些品牌创建、验证和启动代理后接收您管理的品牌的消息。

当客户向您管理的代理发送消息时，Business Messages 会向您的网络钩子发送一个包含各种 ID、消息内容和位置信息的 JSON 载荷。

使用 Business Communications Developers 日志页面调试消息传送问题。

处理收到的邮件

代理处理和响应用户消息的方式在很大程度上取决于业务逻辑。但是，响应用户消息的步骤通常一致。

确认消息

如需确认网络钩子收到的消息，请对发送到网络钩子的消息返回有效的 HTTP 响应。

如果由于传送超时、网络钩子可访问性、重定向或权限问题而导致消息传送失败，Google 会在 7 天内或多次尝试转发后存储并转发消息，直到网络钩子成功收到消息为止。

验证邮件是否来自 Google

在处理消息内容之前，您应该验证 Google 是否发送了消息。

为验证 Google 是否向您发送了邮件，

  1. 解析消息的 X-Goog-Signature 标头。这是消息正文载荷的经过哈希处理、 base64 编码的副本。

  2. 使用客户端令牌（在配置网络钩子时提供）作为密钥，创建消息载荷字节的 SHA512 HMAC，并对结果进行 base64 编码。

  3. 将 X-Goog-Signature 哈希与您创建的哈希进行比较。

    • 如果哈希值匹配，则表示您已确认 Google 发送了消息。
    • 如果哈希值不匹配，请检查已知良好消息的哈希处理过程。如果您的哈希处理流程正常运行，并且您认为收到的是欺诈性邮件，请 与我们联系（您必须使用 Business Messages Google 帐号登录）。

请参阅 GitHub 代码库中适用于 Java、Node.js 和 Python 的 Echo Bots 的消息验证示例。

识别语言区域

用户会在各地以多种语言沟通。Business Messages 使用 resolvedLocale 和 userDeviceLocale 字段表示用户的语言偏好设置，这两个字段取决于用户设备的语言区域设置。 请参阅本地化和语言区域。

请尽可能根据用户的语言偏好设置转送消息和撰写回复。

根据上下文来转送消息

消息上下文可告知用户可能需要的信息类型。 例如，如果用户发送包含 placeId 值的消息，则他们会向特定位置（由 placeId 标识）发送消息，并可能会询问特定于位置的问题。同样地，如果消息的 nearPlaceId 值用于标识用户附近的位置，用户很可能希望了解特定于位置的信息，但在开始对话之前，代理应确认用户想要聊天的位置。

使用消息的上下文信息，将消息路由到最适合响应的位置：

  • 如果消息出现在新对话中，并且是常见问题，您可以使用自动化功能进行回复。
  • 如果自动化功能无法处理此问题，请将其转交给人工客服。
  • 如果消息的语言区域与代理的默认语言区域不匹配，请将消息路由到可以支持该语言区域的实时代理。
  • 如果问题与特定地点有关，请将其转给掌握该位置信息的人员。
  • 如果消息在进行中的对话中，请将其路由至参与对话的实时代理。

确定用户发送的邮件类型

用户可以发送三种类型的消息：

  • 文本消息是自由格式响应。
  • 图片消息包含用户上传的图片的签名网址。
  • 建议消息包含用户点按的建议操作或建议回复的回传数据和文字。

处理邮件内容

如果您的代理使用自动化功能，则用户消息的内容应指导代理的逻辑以及对话中的下一个响应。

识别用户意图的最简单方法是使用建议回复或建议操作中的回传数据。无论与建议关联的文本是什么，回传数据都是机器可读的。

如果用户发送短信，则代理可能会解析受支持关键字的响应，或使用自然语言理解功能（例如通过 Dialogflow 集成处理用户消息并识别正向路径）。

如果您的代理不知道如何响应用户的消息，它应该以错误状态做出响应，并尝试通过提示用户提供更多信息、要求以其他方式进行输入或将对话交给在线客服人员继续对话。

回复用户

通过自动化或实时代理确定正确的响应后，代理会发送消息并继续与用户对话。

编写响应时，请考虑用户的语言区域。此外，您还可以从收到的每条消息中的 userInfo 对象检索值来自定义响应。

消息类型

以下代码展示了代理如何接收消息。

如需了解格式设置和值信息，请参阅 UserMessage。

文字

用户回复最常见方法是使用纯文本。短信采用以下格式。

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

如需了解格式设置和值选项，请参阅 Message。

映像

除了发送短信外，用户还可以将图片作为消息发送到代理。Business Messages 会将共享的图片存储在签名网址中 7 天，并将这些网址包含在消息载荷的 text 字段中。

如果代理包含自动化功能，请确保自动化功能知道在用户分享图片时如何响应。对于实时代理，请确保图片已通过，或者消息中的网址可点击。

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

如需了解格式设置和值选项，请参阅 Message。

建议

借助建议的回复和建议操作，用户只需点按一下即可回复或执行操作。当用户点按建议时，代理会接收到包含建议文本和回传数据的载荷。

建议消息采用以下格式。

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

如需了解格式设置和值选项，请参阅 SuggestionResponse。

身份验证请求

通过身份验证请求建议，用户可以使用 OAuth 提供方登录，向代理提供身份详细信息，或允许代理代表用户执行操作。请参阅使用 OAuth 进行身份验证。

如果用户使用指定的 OAuth 提供方成功登录，则代理将收到包含授权代码的载荷。如果用户登录失败，代理将收到包含错误详情的载荷。

身份验证请求消息采用以下格式。

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

如需了解格式设置和值选项，请参阅 AuthenticationResponse。

消息上下文

每条消息都包含有关消息来源的背景信息。

...
  "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",
    },
  },
...
字段 说明
customContext 合作伙伴指定的上下文数据。
entryPoint 用户发起对话的消息接口，由 EntryPoint 定义。
placeId 来自用户地点的 Google Places 数据库中的唯一标识符。它仅出现在来自特定位置的入口点的消息中。
nearPlaceId 来自 Google 地点数据库中唯一标识符，表示本地包中的第一个位置。收到 nearPlaceId 值时，确认用户想要与之聊天的位置。
deflectedPhoneNumber 在对话开始时，Business Messages 让用户无法拨打电话的电话号码。
resolvedLocale

用户语言区域（在 userDeviceLocale 中报告）与代理支持的语言区域（由指定的对话设置决定）的最佳匹配。请参阅本地化和开始对话。

语言区域值是格式正确的 IETF BCP 47 语言标记。
userInfo.displayName 发送消息的用户的姓名。如果用户选择停用身份共享，则此字段为空。
userInfo.userDeviceLocale 用户的语言区域，由其设备报告，采用格式正确的 IETF BCP 47 语言标记。
widget.url 启动对话平台的网站的网址。
widget.widgetContext 用于启动对话的微件的 data-bm-widget-context 属性值。

对话记录

Google 不会提供对话记录。请以符合您隐私权政策和最佳做法的方式维护自己的历史对话，以便就用户日后发送的消息发送明智的响应。