接收事件

您的代理会从 RBM 平台接收网络钩子事件，从而通知您用户互动和平台级更新。

这些事件按来源分类：

  • 用户事件：从用户设备发送到代理的通知，表示用户与代理或代理的消息进行了互动。
  • 平台事件：RBM 平台发送的有关代理启动状态更改和消息过期的通知。

如需详细了解代理发送给用户设备的状态事件，请参阅发送事件。

用户事件

用户事件是指来自用户设备的通知，用于报告消息状态或订阅变更（即用户已在 Google 信息中取消订阅或重新订阅）。

如需了解完整的格式设置和值选项，请参阅 UserEvent 参考文档。

用户收到客服人员消息

此事件表示消息已成功传递到用户的设备。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

用户阅读代理消息

此事件表示消息已被打开或确认。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

用户开始输入

此事件表示用户正在输入回答。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

用户发送短信

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

用户发送文件

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

用户点按建议的回复

当用户点按建议的回复时，代理会收到一个事件，其中包含回复的回传数据和文本。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

用户点按建议的操作

当用户点按建议的操作时，您的代理会收到一个包含该操作的回传数据的事件。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

用户退订了相应对话

此事件表示用户已退订来自您的代理及其所代表的商家的非必需消息（例如促销消息）。用户通过在 Google 信息中退订 RBM 对话来触发此事件。

以下是 JSON 载荷的示例：

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

退订的运作方式

  • 您始终可以在聊天菜单中找到退订选项。对于促销和多用途代理，此选项也会在聊天中直接显示，但前提是未读消息达到一定数量（具体规则因国家/地区而异）。

  • 选择退订会同时触发两项操作：Google 信息会向您的代理发送特定于国家/地区的关键字（例如“停止”），并且 RBM 平台会向您的 webhook 发送 UNSUBSCRIBE 事件。

    关键字由用户电话号码的双字母国家/地区代码确定。下表列出了每个受支持国家/地区的关键字。

    国家/地区（国家/地区代码） 退订关键字
    美国 (US)、印度 (IN)、英国 (GB)、德国 (DE) 停止
    西班牙 (ES)、墨西哥 (MX) BAJA
    法国 (FR) 停止
    巴西 (BR) parar

  • 用户退订后，除非对话被举报为垃圾内容，否则会保留在用户的收件箱中；如果被举报为垃圾内容，则会移至垃圾内容和已屏蔽对话文件夹。

  • 为识别政策和业务规则违规行为，Google 会在用户退订后监控消息模式。

业务规则

  • 作为管理此对话的 RBM 合作伙伴，您有责任遵守用户取消订阅的请求。
  • 如果您无法在消息串中取消订阅，则必须立即发送确认消息，其中包含指向网站或应用的直接链接，以便用户管理其订阅偏好设置。
  • 用户退订后，禁止发送非必需消息。
  • 仍允许发送重要消息。其中包括：
    • 身份验证信息，例如动态密码 (OTP)
    • 用户已请求并同意接收的特定服务相关的通知
    • 确认用户已取消订阅，并提供有关如何进一步管理其通信偏好的信息

示例

如果用户退订了使用场景为多用途的航空公司代理，您必须停止发送营销消息。不过，如果用户明确同意接收特定航班的最新信息，您可以发送航班最新信息。

退订原因

当用户取消订阅您的代理时，可以选择以下原因：

  • 垃圾内容
  • 从未注册
  • 消息过多
  • 不再感兴趣
  • 其他

退订原因会显示在 Google Analytics 概览中，以帮助合作伙伴了解用户退订的原因。

用户重新订阅对话

此事件表示用户希望再次接收您的代理发送的消息，包括促销等非必需内容。用户可以在 Google 信息中重新订阅之前取消订阅的对话，从而触发此事件。

以下是 JSON 载荷的示例：

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

重新订阅的运作方式

  • 用户可以通过聊天菜单和聊天中的链接使用订阅选项，重新订阅之前已退订的对话。

  • 选择订阅会同时触发两项操作：Google 信息会向您的代理发送特定于国家/地区的关键字（例如“开始”），而 RBM 平台会向您的 webhook 发送 SUBSCRIBE 事件。具体关键字取决于用户电话号码的两个字母的国家/地区代码。下表列出了每个支持的国家/地区的关键字。

    国家/地区（国家/地区代码） 订阅关键字
    美国 (US)、印度 (IN)、英国 (GB)、德国 (DE) 开始
    西班牙 (ES)、墨西哥 (MX) ALTA
    法国 (FR) Démarrer
    巴西 (BR) começar

业务规则

  • 作为管理此对话的 RBM 合作伙伴，您有责任遵守用户重新订阅的请求。
  • 重新订阅适用于所有消息类型，包括促销等非必要内容。
  • 如果用户在退订后向您的商家发送消息，则可将其视为重新订阅请求。
  • 如果用户在消息传递渠道之外（例如在您的网站上）重新订阅，作为 RBM 合作伙伴，您有责任更新其状态并相应地恢复发送消息。

平台事件

RBM 平台会发送平台事件，以通知代理有关代理启动状态或消息过期的更改。

代理发布状态已更改

RBM 平台会针对代理的发布状态的每次更改发送 AgentLaunchEvent。例如，当代理的状态从 PENDING 更改为 LAUNCHED 时。该事件以 Pub/Sub 消息的形式传送。为了与其他事件区分开来，请检查 message.attributes.type 路径是否包含值 agent_launch_event。

Webhook 配置

您可以使用合作伙伴级或代理级网络钩子来接收这些通知。

前提条件

  • 为 RBM 消息传递配置网络钩子（这是接收用户信息和用户活动的必要条件）。
  • 如需区分用户事件和代理启动状态事件，请检查 message.attributes.type 路径是否包含值 agent_launch_event。

事件载荷结构

AgentLaunchEvent 以 Pub/Sub 消息的形式传送。示例如下：

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

事件载荷中的 AgentLaunchEvent.LaunchState 字段表示代理的新启动状态。可能的值如下：

值 代理发布状态 详细信息
UNLAUNCHED 未发布 允许修改。
PENDING 待处理 该请求已发送给运营商进行审核。
LAUNCHED 已发布 允许在指定运营商网络中发送消息。
REJECTED 在特定运营商处遭拒 拒绝原因在注释中指定。
SUSPENDED 在指定运营商处暂停 中止原因在注释中指定。

数据字段包含一个采用 Base64 编码的 JSON 对象，其中包含启动状态详细信息。以下是解码后的 JSON 示例：

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

下表显示了代理启动状态以及触发这些状态的操作：

旧的发布状态 新启动状态 触发变更
PENDING LAUNCHED 待代理批准。
PENDING REJECTED 待处理的代理已被拒绝。
LAUNCHED SUSPENDED 已暂停启动的代理。
SUSPENDED LAUNCHED 已暂停的代理已重新激活。
SUSPENDED TERMINATED 已终止暂停的代理。
TERMINATED LAUNCHED 已启动终止的代理。

消息已过期；撤消成功

此事件表示相应消息的存留时间 (TTL) 已过期，并且该消息已成功撤消。这对于后备消息传递策略来说是一个不错的触发条件。

如需了解完整的格式设置和值选项，请参阅 ServerEvent 参考文档。

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

消息已过期；撤消失败

此事件表示相应消息的 TTL 已过期，但未成功撤消。

如需了解完整的格式设置和值选项，请参阅 ServerEvent 参考文档。

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

无法保证消息传送成功。

  • 如果消息已成功递送，您会在 webhook 中收到 DELIVERED 事件。
  • 如果消息未送达，请使用撤消 API 发送撤消请求。

如果消息具有时效性（例如 OTP 或欺诈警报），最好通过备用渠道（例如短信）发送消息，即使这会导致用户收到重复消息。

上一页
发送事件
下一页
功能检查