接收事件

您的代理会从 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",
  "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 信息会向您的代理发送一个特定于国家/地区的关键字（例如“STOP”），而 RBM 平台会向您的 webhook 发送一个 UNSUBSCRIBE 事件。

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

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

  • 用户退订后，对话仍会保留在收件箱中，除非被举报为垃圾内容，在这种情况下，对话会移至垃圾内容和已屏蔽对话文件夹。

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

业务规则

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

示例

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

退订原因

当用户退订您的代理时，他们可以从以下选项中选择原因：

  • 消息过多
  • 我从未订阅此内容
  • 我不再感兴趣
  • 疑似诈骗
  • 其他

为了减少选择性偏差，前四个选项会以随机顺序向每位用户显示。此顺序在用户访问期间保持一致，其他始终固定在底部。

退订原因会汇总并显示在数据分析概览中，以帮助您了解用户退订的原因。

用户重新订阅对话

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

以下是 JSON 载荷示例：

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

重新订阅的运作方式

  • 订阅选项（可通过聊天菜单和聊天中的链接访问）允许用户重新订阅他们之前已退订的对话。

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

    国家/地区（国家/地区代码） 订阅关键字
    美国 (US)、印度 (IN)、英国 (GB)、德国 (DE)、荷兰 (NL) 开始
    西班牙 (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 字段表示代理的新发布状态。可能的值如下：

值 代理发布状态 详细信息
PENDING 待处理 该请求已发送给运营商进行审核。
LAUNCHED 已发布 允许在指定运营商的网络上发送消息。
REJECTED 在特定运营商处被拒 拒绝原因已在评论中说明。
SUSPENDED 在指定运营商处暂停 中止原因在评论中指定。
UNLAUNCHED 未发布 对于已从所有运营商处取消发布的代理，可以进行修改。

数据字段包含一个 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 UNLAUNCHED 终止代理。
REJECTED LAUNCHED 批准之前被拒绝的发布请求。

合作伙伴发起的发布状态变更

以下是通常由合作伙伴处理的允许转换：

旧发布状态 新发布状态 触发操作
UNSPECIFIED PENDING 提交审核。
PENDING UNLAUNCHED 取消待处理的发布请求。
UNLAUNCHED PENDING 提交审核。
REJECTED PENDING 重新提交审核。
SUSPENDED PENDING 重新提交审核。

消息已过期；撤消成功

此事件表示消息的存留时间 (TTL) 已过期，并且消息已成功撤消。这是触发后备消息策略的绝佳时机。

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

消息已过期；撤消失败

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

无法保证消息一定能送达。

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

如果消息具有时效性（例如动态密码或欺诈提醒），最好通过短信等备用渠道发送消息，即使这会导致向用户发送重复消息。

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