活动

事件是指您的代理人可以发送和接收的通知。事件分为三种类型：

服务器生成的事件

RBM 平台会发送事件来通知您的代理有关服务器级别的更新，例如 消息过期。

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

代理启动状态已更改

RBM 平台会在代理启动状态发生每次更改时发送 AgentLaunchEvent。例如，当您的代理状态在承运人批准后从 PENDING 变为 LAUNCHED 时，您将收到一个 AgentLaunchEvent 事件来指示这一变化。这些事件会发送给所有 RBM 代理，用于所有载体发射状态的更改。

Webhook 配置

您可以使用合作伙伴级别或代理级别的 webhook 来接收这些通知。

前提条件

  • 配置您的 webhook以进行 RBM 消息传递（这是接收用户消息和用户生成事件的必要条件）。
  • 为了区分 用户生成的事件 和代理启动状态事件，请检查 message.attributes.type 路径的值 agent_launch_event。

事件有效载荷结构

AgentLaunchEvent 以发布/订阅消息的形式传递。示例如下：

{
  "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 终止代理已启动。

消息已过期；撤销成功

该消息已过期并已成功撤回。这次事件将是一个很好的触发点，可以启动你的备用信息传递策略。

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

邮件已过期；撤销失败

该消息已过期，但未被撤回。

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

信息送达无法保证。

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

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

用户生成的活动

与用户消息和功能检查一样，代理会以 JSON 格式接收用户事件。

如需了解格式设置和值选项，请参阅 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 对话。

UNSUBSCRIBE 事件表示用户已退订与您的代理及其所代表的商家的对话。以下是 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 Messages 中取消订阅的对话。

SUBSCRIBE 事件表示用户希望接收来自您的代理的消息，包括促销等非必要内容。以下是一个 JSON 有效负载示例：

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

运作方式

  • 用户可以通过聊天菜单和聊天内链接使用 Subscribe 选项重新订阅他们已取消订阅的对话。

  • 选择 订阅 会同时触发两个操作：Google Messages 会向您的代理发送特定国家/地区的关键字（例如，“START”），RBM 平台会向您的 webhook 发送 SUBSCRIBE 事件。

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

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

业务规则

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

代理生成的事件

您的代理会发送事件来模拟人类互动，并向用户保证您的代理正在处理他们的消息。对于用户，事件会显示为对话中的通知。

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

代理发送 READ 事件

对于用户而言，此事件表示特定消息的已读回执。这样一来，用户便会知道 RBM 平台已传送其消息，并且代理正在处理该消息。

以下代码会针对具有匹配 messageId 的消息发送 READ 事件。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 此代码摘自 RBM 代理示例。

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 此代码摘自 RBM 代理示例。

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 此代码摘自 RBM 代理示例。

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 此代码摘自 RBM 代理示例。

代理发送 IS_TYPING 事件

对于用户而言，此事件会显示为输入指示器，让用户知道您的代理正在撰写消息。输入指示器会在短时间（大约 20 秒）后或在用户设备收到客服人员发送的新消息时失效。您的代理可以发送多个 IS_TYPING 事件来重置输入指示器的过期计时器。

以下代码会发送 IS_TYPING 事件。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 此代码摘自 RBM 代理示例。

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 此代码摘自 RBM 代理示例。

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 此代码摘自 RBM 代理示例。

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 此代码摘自 RBM 代理示例。
上一页
接收消息
下一页
功能检查