活动

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

服务器生成的事件

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

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

代理发布状态已更改

RBM 平台会针对代理的每次发布状态更改发送 AgentLaunchEvent。例如，当代理的状态在获得运营商批准后从 PENDING 变为 LAUNCHED 时，您会收到一个 AgentLaunchEvent 事件来指示此更改。这些事件会针对所有 RBM 代理发送，用于所有运营商发布状态更改。

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

消息已过期；撤消成功

相应消息已过期，并已成功撤消。此事件非常适合作为后备消息传递策略的触发条件。

{
  "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 信息中重新订阅之前取消订阅的对话。

SUBSCRIBE 事件表示用户希望接收来自您的代理的消息，包括促销等非必需内容。以下是 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 合作伙伴，您有责任更新其状态并相应地恢复发送消息。

代理生成的事件

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

如需了解格式设置和值选项，请参阅 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 示例代理。
上一页
接收消息
下一页
功能检查