接收消息

在您向 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.jsPython

识别语言区域

用户会在各地以多种语言沟通。Business Messages 代表用户的resolvedLocaleuserDeviceLocale 字段(具体取决于用户的设备)语言区域设置。 请参阅本地化和语言区域

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

根据上下文路由消息

消息上下文用于说明用户可能在寻找哪些类型的信息。 例如,如果用户发送包含 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 不提供对话记录。保留您自己的历史数据 遵循您的隐私权政策和最佳做法, 这样,您便可以针对用户日后发送的消息发送明智的响应。