接收消息

在您向 Google 商家信息注册后 信息、 您可以代表测试代理接收邮件。您可以接收消息 适用于您之后管理的品牌 create， 验证和 启动 这些品牌的代理

当客户向您管理的客服人员发送消息时，Business Messages 将 JSON 载荷发送到 webhook，其中包含各种 ID、消息内容 和位置信息

使用 Business Communications 开发者控制台日志 页面 调试邮件递送问题。

处理传入消息

代理如何处理和响应用户消息在很大程度上取决于 业务逻辑但通常情况下，响应用户的步骤 保持一致。

确认消息

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

如果消息由于传送超时、webhook 可达性、 重定向或权限问题，Google 会存储和转发该消息，同时 多次重试，持续 7 天或直至 webhook 成功收到 消息。

验证消息是否来自 Google

您应先验证消息是 Google 发送的，然后再处理消息 内容。

为了验证 Google 是否确实向您发送了一条消息，

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

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

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

    • 如果哈希值一致，则表示您已确认该邮件是 Google 发送的。
    • 如果哈希值不匹配，请基于已知良好的密钥检查您的哈希处理过程 消息。如果您的哈希处理过程正常运行，并且收到了 您认为以欺诈方式发送给您的邮件， 与我们联系（您必须先签署 在使用 Business Messages Google 账号）。

查看 GitHub 代码库中针对 Echo 聊天机器人的消息验证示例 使用 Java 编写； Node.js 和 Python。

识别语言区域

用户会在各地以多种语言沟通。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。

身份验证请求

Authentication 请求建议允许用户使用 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 商家信息数据库中营业地点的唯一标识符 发送给用户的请求它只会出现在来自特定位置的邮件中 入口点。
nearPlaceId Google 商家信息数据库中第一个地点的唯一标识符。 本地软件包中的某个位置。确认用户想要聊天的地点 收到 nearPlaceId 值时的值。
deflectedPhoneNumber Business Messages 用于转移用户，使其无法致电的电话号码 对话开始的时间。
resolvedLocale

计算出的用户语言区域的最佳匹配结果（以 userDeviceLocale）和代理支持的语言区域 （取决于指定的对话设置）。请参阅 本地化 和 开始 对话。

语言区域值是格式正确的 IETF BCP 47 语言标记。

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

对话记录

Google 不提供对话记录。保留您自己的历史数据 遵循您的隐私权政策和最佳做法， 这样，您便可以针对用户日后发送的消息发送明智的响应。