发送消息

RBM 代理通过发送和接收消息与用户进行通信。 如需向用户发送消息，代理会向 RCS Business Messaging API 发送消息请求。单个请求可以包含文本、富卡片、媒体和 PDF 文件，以及建议的回复和建议的操作。

在某些情况下，RBM 平台会返回错误，以帮助您管理消息传送：

• 如果您向设备不支持 RCS 或未启用 RCS 的用户发送消息，RBM 平台会返回 404 NOT_FOUND 错误。在这种情况下，您可以尝试通过基础架构中定义的回退方法与用户联系。
• 如果您向某个网络上的 RCS 用户发送消息，但您的代理尚未在该网络上启动，或者该网络尚未启用 RCS 流量，则 RBM 平台会返回 404 NOT_FOUND 错误。
• 如果您发送的消息包含用户设备不支持的功能，RBM 平台会返回 400 INVALID_ARGUMENT 错误，并且不会传送您的消息。

作为多渠道消息传递策略的一部分，最好撤消在合理时间后未送达的消息，并通过其他渠道发送这些消息。如需在预定义的时间自动撤消消息，请设置消息过期时间。

收件人已离线

如果收件人处于离线状态，RBM 平台仍会接受消息以进行递送。您会收到 200 OK 响应，RBM 平台会保留该消息并尝试在 30 天内重新传送。您无需让 RBM 再次发送消息。

RBM 会在未送达的消息提交 30 天后将其删除。

根据代理的用例，您可能需要在 30 天的超时期限之前撤消未送达的消息。撤消可以防止离线用户在重新上线时收到过时的消息。您可以通过多种方式撤消消息：

• 发送撤消请求以触发撤消。
• 设置邮件失效时间，以便在适当的时间自动撤消邮件。

设置邮件失效日期

代理的消息是否具有时效性？例如，一次性密码仅在短时间内有效。限时优惠过期。预约提醒在预约日期之后便不再相关。为了确保消息的及时性和相关性，请设置消息过期时间。这样可以防止离线用户在重新上线时收到过时的内容。过期也是一个很好的提示，可用于调用您的后备消息传递策略，以便用户及时获得所需信息。

如需设置消息过期时间，请在代理消息中指定以下字段之一：

• expireTime：消息失效的确切时间（以世界协调时间 [UTC] 表示）。
• ttl（存留时间）：消息失效之前的时间。

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

消息过期后，RBM 平台会停止尝试传递该消息，并且该消息会自动撤消。不过，在极少数情况下，此操作可能会失败。例如，在 RBM 平台正在传送消息时，API 可能会触发撤消操作。为了确认过期消息是否已成功撤消，RBM 会向您的 webhook 发送通知事件。

ttl 和 expireTime 的最大值为消息提交后的 15 天。

虽然没有最低值 ttl 和 expireTime，但建议在提交消息后至少等待 10 秒，以显著降低同时收到撤消通知和递送通知的几率。

设置消息流量类型

RBM API 包含一个 messageTrafficType 字段，用于对消息进行分类。虽然代理用例仍然定义了代理行为以及适用的业务规则，但 messageTrafficType 允许对消息内容进行更详细的分类。最终，这将使单个代理能够处理多种使用情形。目前，现有代理使用情形或业务规则不会受到影响。

此字段为选填字段，但建议您现在就设置此字段，以免在它成为必填字段时收到错误消息。

如需设置消息流量类型，请根据每条消息的内容为其分配相应的 messageTrafficType。RBM 支持以下流量类型。

流量类型	消息内容	代理使用场景
AUTHENTICATION	用于身份验证消息。	动态密码
TRANSACTION	针对与用户现有服务或产品相关的消息。例如：确认信息、付款收据或预订详情。	交易型或多次使用
PROMOTION	对于优惠、折扣、公告或其他促销内容等促销消息。	宣传性或多次使用
SERVICEREQUEST	对于用户明确请求的服务，系统会发送相关消息。	一次性密码、交易性、促销性或多用途
ACKNOWLEDGEMENT	用于确认用户操作（尤其是退订请求）的消息。此邮件旨在确认我们已收到用户的申请，并且正在处理该申请。	一次性密码、交易性、促销性或多用途

如果未设置流量类型，系统会为代理的使用情形分配默认类型。

代理使用场景	默认流量类型
OTP	AUTHENTICATION
事务性	TRANSACTION
宣传	PROMOTION
多用途	MESSAGE_TRAFFIC_TYPE_UNSPECIFIED

多用途代理没有默认流量类型。您必须根据每条消息的内容，明确设置其流量类型。如果您不替换 MESSAGE_TRAFFIC_TYPE_UNSPECIFIED 值，则会出错。

消息大小限制

整个序列化 AgentMessage 的最大大小为 250 KB。消息的文本部分有自己的限制，不得超过 3072 个字符。

通过 RBM 发送的文件大小上限为 100MB。如需了解详情，请参阅媒体文件和 PDF 文件。

重要提示： 对于美国境内的 RBM 流量：为防止美国境内的用户产生意外的数据流量消耗，发送到美国电话号码的单个 RBM 消息中的所有媒体和 PDF 附件的总大小不得超过 100 MiB。（1 MiB = 1,048,576 字节）。此限制仅适用于美国运营商的 RBM 流量。例如，如果客服人员在多个国家/地区（例如加拿大和美国）工作，则此限制仅影响发送到美国号码的消息。

文本

最简单的消息由文本组成。短信最适合在不需要视觉元素、复杂互动或回复的情况下传递信息。

示例

以下代码会发送纯文本消息。如需了解格式设置和值选项，请参阅 phones.agentMessages.create。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!"
  },
  "messageTrafficType": "PROMOTION"
}'

Node.js

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

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
};

// Send a simple message to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.rbm.RbmApiHelper;
…

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

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]"
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create a simple RBM text message
message_text = messages.TextMessage('Hello, world!')

# Send text message to the device
messages.MessageCluster().append_message(message_text).send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using RCSBusinessMessaging;
…

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
);

此代码摘自 RBM 示例代理。

基本消息内容 - 短信转换

运营商已推出结算模式，以支持将短信迁移到 RBM。包含最多 160 个 UTF-8 字符的 RBM 消息称为基本消息。

在构建发送基本消息的请求时，请注意字符按 1 字节 (UTF-8) 计算。如果您发送的消息包含特殊字符（例如表情符号或多字节字符集），则每个字符会占用 2-4 个或更多 UTF-8 字符。

在框中输入一些文字，以检查其长度：

基本消息内容和链接预览

RCS 客户端可能会实现链接预览功能。如果纯文字 RBM 消息包含带有 OpenGraph 标记的网站的网址，则可能会显示预览图片，从而给人以内容更丰富的印象。

请注意，RCS 客户端可能允许用户停用链接预览。

用于用户验证的一次性密码

您可以使用 RBM 通过 SMS Retriever API 发送一次性密码 (OTP) 以自动验证用户身份。没有专门用于读取通过 RBM 收到的 OTP 的 API。

Android 设备上的运作方式

对于已向 SMS Retriever API 注册的 Android 应用，该 API 会监听格式正确的 RBM 消息。此消息必须包含 OTP 和用于标识应用的唯一哈希值。

当收到格式正确的 RBM 消息时，SMS Retriever API 会像处理 SMS OTP 一样处理该消息。在哈希与您的应用匹配后，系统会提取 OTP 并将其转发给您的应用，以自动验证用户身份。

• 用于用户验证的 RBM 短信示例：Your code is <OTP> <app hash>.
• 示例：Your code is 123456 M8tue43FGT.

如需详细了解 SMS Retriever 及相关 API，请参阅 SMS Retriever 文档。如需详细了解已向 SMS Retriever API 注册的应用中的自动用户验证，请参阅此流程图。

iOS 版的运作方式

对于 iOS，系统的内置 OTP 处理功能会自动检测 RBM OTP 并建议自动填充，就像处理短信 OTP 一样。iOS 应用无需进行特定的 API 集成即可读取 OTP。

媒体文件和 PDF 文件

当您发送包含图片、视频、音频或 PDF 文件的消息时，客服人员必须提供可公开访问的内容网址或直接上传文件。对于媒体文件，您还可以指定缩略图，以便用户在点击之前预览内容。对于音频文件，系统会使用默认音频 widget 作为占位符。

重要提示： 为了保护用户隐私和安全，RBM 平台会先从提供的网址下载媒体文件和 PDF 文件并进行处理，然后再将它们传送给用户。这样可以防止通过唯一网址跟踪代理。因此，请勿提交大量唯一网址。无论网址指向的是相同的文件还是不同的文件，RBM 平台都不支持此操作。对于相同的文件，请使用相同的网址。

RBM 平台会将文件缓存 60 天，并且 API 会返回一个文件 ID，您的代理可以在发送给用户的消息中添加该 ID。60 天后，RBM 会从缓存中移除文件。

通过网址指定文件时，最佳做法是将 contentMessage.forceRefresh 设置为 false。将 contentMessage.forceRefresh 设置为 true 会强制 RBM 从指定网址提取新内容，即使该网址内容已缓存也是如此，这会增加用户的消息传送时间。

请参阅有关文件大小建议和限制的最佳实践。

文件网址示例

以下代码会发送图片。如需了解格式设置和值选项，请参阅 AgentContentMessage。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "contentInfo": {
      "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif",
      "forceRefresh": false
    }
  }
}'

Node.js

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

let params = {
   fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
   msisdn: '[phone]',
};

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage;
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage;
import com.google.rbm.RbmApiHelper;
…

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

   String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

   // create media only message
   AgentContentMessage agentContentMessage = new AgentContentMessage();
   agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl));

   // attach content to message
   AgentMessage agentMessage = new AgentMessage();
   agentMessage.setContentMessage(agentContentMessage);

   rbmApiHelper.sendAgentMessage(agentMessage, "[phone]");
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create media file attachment
file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif')

messages.MessageCluster().append_message(file_message).send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

// Create content info with the file url
ContentInfo contentInfo = new ContentInfo
{
    FileUrl = fileUrl
};

// Attach content info to a message
AgentContentMessage agentContentMessage = new AgentContentMessage
{
    ContentInfo = contentInfo,
};

// Attach content to message
AgentMessage agentMessage = new AgentMessage
{
    ContentMessage = agentContentMessage
};

rbmApiHelper.SendAgentMessage(agentMessage, "[phone]");

此代码摘自 RBM 示例代理。

或者，您也可以先上传媒体，然后再通过 files.create 将其添加到消息中。

文件上传示例

以下代码会上传一个视频文件和一个缩略图文件，然后通过一条消息发送这两个文件。如需了解格式设置和值选项，请参阅 files.create 和 AgentContentMessage。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \
-H "Content-Type: video/mp4" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
--upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"

# Capture server-specified video file name from response body JSON


curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \
-H "Content-Type: image/jpeg" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
--upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"

# Capture server-specified image file name from response body JSON


curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "uploadedRbmFile": {
      "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME",
      "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME"
    }
  }
}'

支持的媒体类型

RBM 支持以下媒体类型。对于缩略图，仅支持 image/jpeg、image/jpg、image/gif 和 image/png。

媒体类型	文档类型	扩展程序	适用于复合信息卡
application/ogg	OGG 音频	.ogx	否
application/pdf	PDF	.pdf	否
音频/aac	AAC 音频	.aac	否
audio/mp3	MP3 音频	.mp3	否
audio/mpeg	MPEG 音频	.mpeg	否
audio/mpg	MPG 音频	.mp3	否
audio/mp4	MP4 音频	.mp4	否
audio/mp4-latm	MP4-latm 音频	.mp4	否
audio/3gpp	3GPP 音频	.3gp	否
image/jpeg	JPEG	.jpeg、.jpg	是
image/gif	GIF	.gif	是
image/png	PNG	.png	是
video/h263	H263 视频	.h263	是
video/m4v	M4V 视频	.m4v	是
video/mp4	MP4 视频	.mp4	是
video/mpeg4	MPEG-4 视频	.mp4、.m4p	是
video/mpeg	MPEG 视频	.mpeg	是
视频/webm	WEBM 视频	.webm	是

建议

代理会在建议条状标签列表（最多 11 条建议）或富卡片（最多 4 条建议）中发送建议（建议的回复和建议的操作）。

每条建议最多可包含 25 个字符。

建议的回复

建议的回复可提供您的代理知道如何回应的回复，从而引导用户完成对话。

当用户点按建议的回复时，您的代理会收到一个包含回复文本和回传数据的事件。载荷最多包含 2048 个字符。

示例

以下代码发送包含两条建议回复的文本。如需了解格式设置和值选项，请参阅 SuggestedReply。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "reply": {
          "text": "Suggestion #1",
          "postbackData": "suggestion_1"
        }
      },
      {
        "reply": {
          "text": "Suggestion #2",
          "postbackData": "suggestion_2"
        }
      }
    ]
  }
}'

Node.js

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

let suggestions = [
   {
      reply: {
         'text': 'Suggestion #1',
         'postbackData': 'suggestion_1',
      },
   },
   {
      reply: {
         'text': 'Suggestion #2',
         'postbackData': 'suggestion_2',
      },
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
import com.google.rbm.SuggestionHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();
   suggestions.add(
      new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply());

   suggestions.add(
      new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply());

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggested replies for the message to send to the user
cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'))
cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2'))

# Send a simple message with suggestion chips to the device
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

List<Suggestion> suggestions = new List<Suggestion>
{
   // Create suggestion chips
   new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(),
   new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply()
};

// Send simple text message with suggestions to user
rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
   suggestions
);

此代码摘自 RBM 示例代理。

建议操作

建议操作利用设备的内置功能引导用户完成对话。您的代理可以建议用户拨打电话号码、在地图上打开某个位置、分享位置、打开网址或创建日历活动。

对于每项建议的操作，您可以选择性地提供一个后备网址（最多 2048 个字符）。如果用户的设备不支持建议的操作，此网址将在新的浏览器窗口中打开。

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

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

拨号

拨号操作会引导用户拨打代理指定的电话号码。 电话号码只能包含数字 (0-9)、加号 (+)、星号 (*) 和井号 (#)。系统支持 E.164 国际格式（例如 [phone]），但这不是必需的。也就是说，[phone] 和 1011 都是有效的条目。

示例

以下代码会发送拨号操作。如需了解格式设置和值选项，请参阅 DialAction。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Call",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/contact/",
          "dialAction": {
            "phoneNumber": "[phone]"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define a dial suggested action
let suggestions = [
   {
      action: {
         text: 'Call',
         postbackData: 'postback_data_1234',
         dialAction: {
            phoneNumber: '[phone]'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a dial suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a dial suggested action
   DialAction dialAction = new DialAction();
   dialAction.setPhoneNumber("[phone]");

   // creating a suggested action based on a dial action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Call");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setDialAction(dialAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create a dial suggested action
suggestions = [
      messages.DialAction('Call', 'reply:postback_data_1234', '[phone]')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

// Create a dial an agent suggested action
DialAction dialAction = new DialAction
{
    PhoneNumber = "[phone]"
};

// Creating a suggested action based on a dial action
SuggestedAction suggestedAction = new SuggestedAction
{
    Text = "Call",
    PostbackData = "postback_data_1234",
    DialAction = dialAction
};

// Attach action to a suggestion
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
    suggestions
);

此代码摘自 RBM 示例代理。

查看地点

“查看位置”操作会在用户的默认地图应用中显示某个位置。您可以通过经纬度或基于用户当前位置的查询来指定位置。您还可以为地图应用中显示的图钉设置自定义标签。

示例

以下代码会发送查看位置信息操作。如需了解格式设置和值选项，请参阅 ViewLocationAction。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "View map",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z",
          "viewLocationAction": {
            "latLong": {
              "latitude": "37.4220188",
              "longitude": "-122.0844786"
            },
            "label": "Googleplex"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define a view location suggested action
let suggestions = [
   {
      action: {
         text: 'View map',
         postbackData: 'postback_data_1234',
         viewLocationAction: {
            latLong: {
               latitude: 37.4220188,
               longitude: -122.0844786
            },
            label: 'Googleplex'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a view location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a view location suggested action
   ViewLocationAction viewLocationAction = new ViewLocationAction();
   viewLocationAction.setQuery("Googleplex, Mountain View, CA");

   // creating a suggested action based on a view location action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("View map");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setViewLocationAction(viewLocationAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create a view location suggested action
suggestions = [
      messages.ViewLocationAction('View map',
            'reply:postback_data_1234',
            query='Googleplex, Mountain View, CA')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

// create an view location action
ViewLocationAction viewLocationAction = new ViewLocationAction
{
    Query = "Googleplex Mountain View, CA"
};

// Attach the view location action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    ViewLocationAction = viewLocationAction,
    Text = "View map",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
    suggestions
);

此代码摘自 RBM 示例代理。

分享位置信息

“分享位置信息”操作可让用户与您的代理分享位置信息。 用户可以分享其当前位置，也可以分享从 Google 地图应用中手动选择的位置。

示例

以下代码会发送分享位置信息操作。如需了解格式设置和值选项，请参阅 ShareLocationAction。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Share your location",
          "postbackData": "postback_data_1234",
          "shareLocationAction": {}
        }
      }
    ]
  }
}'

Node.js

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

// Define a share location suggested action
let suggestions = [
   {
      action: {
         text: 'Share your location',
         postbackData: 'postback_data_1234',
         shareLocationAction: {
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a share location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a share location suggested action
   ShareLocationAction shareLocationAction = new ShareLocationAction();

   // creating a suggested action based on a share location action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Share location");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setShareLocationAction(shareLocationAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create a share location suggested action
suggestions = [
      messages.ShareLocationAction('Share location',
            'reply:postback_data_1234')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

// Create a share location action
ShareLocationAction shareLocationAction = new ShareLocationAction();

// Attach the share location action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    ShareLocationAction = shareLocationAction,
    Text = "Share location",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
    suggestions
);

此代码摘自 RBM 示例代理。

打开网址

借助“打开网址”操作，您可以将用户引导至代理指定的网页。 默认情况下，网页会在用户的浏览器中打开。如果用户为网页配置了默认应用，则系统会打开该应用。在这种情况下，建议操作按钮上的图标将是应用的图标。

“打开网址”操作还支持集成式 WebView；请参阅使用 WebView 打开网址。

示例

以下代码会发送打开网址操作。如需了解格式设置和值选项，请参阅 OpenUrlAction。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Open Google",
          "postbackData": "postback_data_1234",
          "openUrlAction": {
            "url": "https://www.google.com"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define an open URL suggested action
let suggestions = [
   {
      action: {
         text: 'Open Google',
         postbackData: 'postback_data_1234',
         openUrlAction: {
            url: 'https://www.google.com'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating an open url suggested action
   OpenUrlAction openUrlAction = new OpenUrlAction();
   openUrlAction.setUrl("https://www.google.com");

   // creating a suggested action based on an open url action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Open Google");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setOpenUrlAction(openUrlAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create an open url suggested action
suggestions = [
      messages.OpenUrlAction('Open Google',
            'reply:postback_data_1234',
            'https://www.google.com')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

// Create an open url action
OpenUrlAction openUrlAction = new OpenUrlAction
{
    Url = "https://www.google.com"
};

// Attach the open url action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    OpenUrlAction = openUrlAction,
    Text = "Open Google",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
    suggestions
);

此代码摘自 RBM 示例代理。

使用 WebView 打开网址

“使用 WebView 打开网址”操作会使用默认浏览器的渲染引擎在即时通讯应用内加载指定的网页。这样一来，用户无需离开 RBM 对话即可与网页互动。如果用户的设备不支持 WebView，网页会在用户的浏览器中打开。如需启用 WebView，请参阅 OpenURLApplication。

WebView 有三种显示模式。如需了解格式设置和值选项，请参阅 WebviewViewMode。

• 完整：网页占据整个屏幕
• 一半：网页占据一半屏幕
• 高：网页占据屏幕的四分之三

示例

以下代码会发送“使用 WebView 打开网址”操作。如需了解格式设置和值选项，请参阅 OpenURLAction。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
 "contentMessage": {
   "text": "Hello, world!",
   "suggestions": [
     {
       "action": {
         "text": "Open Google",
         "postbackData": "postback_data_1234",
         "openUrlAction": {
           "url": "https://www.google.com",
           "application": "WEBVIEW",
           "webviewViewMode": "FULL",
           "description": "Accessibility description"
         }
       }
     }
   ]
 }
}'

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…
  
try {
  
   String URL = "https://www.google.com";
  
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();
  
   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // Create suggestion to view webpage in full mode
   Suggestion viewInFullMode =  getUrlActionInWebview(URL, "FULL")
   suggestions.add(viewInFullMode);
  
   // create suggestion to view webpage in half mode
   Suggestion viewInHalfMode =  getUrlActionInWebview(URL, "HALF")
   suggestions.add(viewInHalfMode);
     
   // create suggestion to view webpage in tall mode
   Suggestion viewInTallMode =  getUrlActionInWebview(URL, "TALL")
   suggestions.add(viewInTallMode);
     
   // Send simple text message with the suggested action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

  /**
    * Creates a suggested action to open URL in webview.
    *
    * @return a suggestion object for an open URL in webview action .
    */
    private Suggestion getUrlActionInWebview(String url,
                                             String viewMode) {
      // create an open url action
      OpenUrlAction openUrlAction = new OpenUrlAction();
      openUrlAction.setUrl(url);
      openUrlAction.setApplication("WEBVIEW");
      openUrlAction.setWebviewViewMode(viewMode);
      openUrlAction.setDescription("Accessibility description");
     
      // attach the open url action to a suggested action
      SuggestedAction suggestedAction = new SuggestedAction();
      suggestedAction.setOpenUrlAction(openUrlAction);
      suggestedAction.setText('display_text');
      suggestedAction.setPostbackData('postback_data_123');
     
      // attach the action to a suggestion object
      Suggestion suggestion = new Suggestion();
      suggestion.setAction(suggestedAction);
     
      return suggestion;
    }

创建日历活动

“创建日历活动”操作会打开用户的日历应用，并开始创建包含指定信息的新活动。

日历活动标题为必填项。最多 100 个字符。日历活动说明是可选的，最多可包含 500 个字符。

示例

以下代码会发送创建日历活动操作。如需了解格式设置和值选项，请参阅 CreateCalendarEventAction。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Save to calendar",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/calendar",
          "createCalendarEventAction": {
            "startTime": "2020-06-30T19:00:00Z",
            "endTime": "2020-06-30T20:00:00Z",
            "title": "My calendar event",
            "description": "Description of the calendar event"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define a create calendar event suggested action
let suggestions = [
   {
      action: {
         text: 'Save to calendar',
         postbackData: 'postback_data_1234',
         createCalendarEventAction: {
            startTime: '2020-06-30T19:00:00Z',
            endTime: '2020-06-30T20:00:00Z',
            title: 'My calendar event',
            description: 'Description of the calendar event',
         },
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a create calendar event suggested action
   CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction();
   calendarEventAction.setTitle("My calendar event");
   calendarEventAction.setDescription("Description of the calendar event");
   calendarEventAction.setStartTime("2020-06-30T19:00:00Z");
   calendarEventAction.setEndTime("2020-06-30T20:00:00Z");

   // creating a suggested action based on a create calendar event action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Save to calendar");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setCreateCalendarEventAction(createCalendarEventAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Create a calendar event suggested action
suggestions = [
      messages.CreateCalendarEventAction('Save to Calendar',
                             'reply:postback_data_1234',
                             '2020-06-30T19:00:00Z',
                             '2020-06-30T20:00:00Z',
                             'My calendar event',
                             'Description of the calendar event')

]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

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

// Create a calendar event action
CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction
{
    Title = "My calendar event",
    Description = "Description of the calendar event",
    StartTime = "2020-06-30T19:00:00Z",
    EndTime = "2020-06-30T20:00:00Z"
};

// Attach the calendar event action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    CreateCalendarEventAction = calendarEventAction,
    Text = "Save to calendar",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
    suggestions
);

此代码摘自 RBM 示例代理。

建议内容信息条列表

您的代理会随消息一起发送建议内容信息卡列表，以引导用户执行后续操作。只有当关联的消息位于对话底部时，芯片列表才会显示。对话中的任何后续消息（无论是用户还是您的代理发送的）都会覆盖功能块列表。

列表中的功能块是建议的回复和建议的操作。

芯片列表最多包含 11 个建议芯片，每个芯片标签最多可包含 25 个字符。

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

复合信息卡

当您需要发送一组相关信息、媒体或建议时，应发送复合信息卡。借助富卡片，代理可以在一条消息中发送多条信息。

富卡片可以包含以下内容：

• 图片或视频
• 标题文本
• 描述文字
• 建议的回复和建议的操作（最多 4 个）

复合信息卡可以包含上述所有项，但信息卡必须包含至少一张图片、一个视频或一个标题才能有效。富卡片最多可以包含四项建议的操作和建议的回复。

代理可以一起发送多张复合信息卡，形成复合信息卡轮播界面。

富卡片载荷的大小上限为 250 KB。如需了解有关媒体文件大小建议和限制的最佳实践，请参阅相关文档。

您可以在复合信息卡中找到复合信息卡规范。

卡片高度

卡片会纵向展开即可适应内容。富卡片的最小高度为 112 DP，最大高度为 344 DP。如果卡片的内容不足以填充最小卡片高度，卡片会展开，并用空白填充多余的高度。

复合信息卡中的媒体必须符合以下三种高度之一：

• 短：112 DP
• 中：168 DP
• 高：264 DP

如果媒体不适合卡片中的尺寸（在给定所选高度的情况下），系统会通过缩放和裁剪媒体来选择媒体预览。

示例

以下代码会发送包含图片和建议回复的富卡片。如需了解格式设置和值选项，请参阅 RichCard。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "richCard": {
      "standaloneCard": {
        "thumbnailImageAlignment": "RIGHT",
        "cardOrientation": "VERTICAL",
        "cardContent": {
          "title": "Hello, world!",
          "description": "RBM is awesome!",
          "media": {
            "height": "TALL",
            "contentInfo":{
              "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif",
              "forceRefresh": false
            }
          },
          "suggestions": [
            {
              "reply": {
                "text": "Suggestion #1",
                "postbackData": "suggestion_1"
              }
            },
            {
              "reply": {
                "text": "Suggestion #2",
                "postbackData": "suggestion_2"
              }
            }
          ]
        }
      }
    }
  }
}'

Node.js

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

// Suggested replies to be used in the card
let suggestions = [
   {
      reply: {
         'text': 'Suggestion #1',
         'postbackData': 'suggestion_1',
      },
   },
   {
      reply: {
         'text': 'Suggestion #2',
         'postbackData': 'suggestion_2',
      },
   },
];

// Image to be displayed by the card
let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif';

// Definition of the card parameters
let params = {
   messageText: 'Hello, world!',
   messageDescription: 'RBM is awesome!',
   msisdn: '[phone]',
   suggestions: suggestions,
   imageUrl: imageUrl,
   height: 'TALL',
};

// Send rich card to device
rbmApiHelper.sendRichCard(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.cards.CardOrientation;
import com.google.rbm.cards.MediaHeight;
import com.google.rbm.RbmApiHelper;
import com.google.rbm.SuggestionHelper;
…

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

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();
   suggestions.add(
      new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply());

   suggestions.add(
      new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply());

   String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

   // Create a standalone rich card to send to the user
   StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard(
       "Hello, world!",
       "RBM is awesome!",
       imageUrl,
       MediaHeight.MEDIUM,
       CardOrientation.VERTICAL,
       suggestions
   );

   rbmApiHelper.sendStandaloneCard(standaloneCard, "[phone]");
} catch(Exception e) {
   e.printStackTrace();
}

此代码摘自 RBM 示例代理。

Python

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

# Suggested replies to be used in the card
suggestions = [
      messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'),
      messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')
]

# Image to be displayed by the card
image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif';

# Define rich card structure
rich_card = messages.StandaloneCard('VERTICAL',
                                    'Hello, world!',
                                    'RBM is awesome!',
                                    suggestions,
                                    image_url,
                                    None,
                                    None,
                                    'MEDIUM')

# Append rich card and send to the user
cluster = messages.MessageCluster().append_message(rich_card)
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
using RCSBusinessMessaging.Cards;
…

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

List<Suggestion> suggestions = new List<Suggestion>
{
   // Create suggestion chips
   new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(),
   new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply()
};

string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

// Create rich card with suggestions
StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard(
   "Hello, world!",
   "RBM is awesome",
   imageUrl,
   MediaHeight.TALL,
   CardOrientation.VERTICAL,
   suggestions
);

// Send rich card to user
rbmApiHelper.SendStandaloneCard(standaloneCard, "[phone]");

此代码摘自 RBM 示例代理。

轮播式复合信息卡

当您需要向用户显示多个选项供其选择时，请使用富卡片轮播界面。轮播界面可将多个富卡片串联在一起，让用户能够比较商品并单独对每个商品做出反应。

轮播界面最少可包含两张复合信息卡，最多可包含十张。轮播界面中的复合信息卡必须符合内容和高度方面的一般复合信息卡要求。您可以在富卡片中找到轮播界面的规范。

富卡片轮播界面的载荷大小上限为 250 KB。如需了解有关媒体文件大小建议和限制的最佳实践，请参阅相关文档。

截断

与富卡片类似，许多因素（例如屏幕分辨率、像素密度和用户偏好设置）都会影响卡片在最终用户面前的显示方式。不过，在轮播界面中，前几个卡片的高度会决定轮播界面中所有卡片的高度，而卡片高度会影响标题、说明和建议的截断。

如果设备因显示限制或卡片高度而无法显示卡片的所有元素，RBM 会截断卡片，直到卡片可以显示在设备上为止，具体采用以下逻辑：

1. 将说明缩减为一行。
2. 将标题缩减为一行。
3. 省略不适合显示在卡片中的建议，从定义的列表末尾开始。
4. 省略说明。
5. 省略标题。

为避免被截断，请尽可能缩短标题和说明的长度。对于竖屏媒体，请使用标题和说明或一条建议。对于中等媒体，最多使用两个建议。对于短媒体，最多使用三条建议。 为了显示四条建议，请勿在卡片中添加媒体内容。

确保卡片在内容大小和长度方面大致相当，如有必要，请在轮播界面中优先显示较大的卡片，以免后续卡片被截断。

示例

以下代码会发送复合信息卡轮播界面。如需了解格式设置和值选项，请参阅 RichCard。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{
  "contentMessage": {
    "richCard": {
      "carouselCard": {
        "cardWidth": "MEDIUM",
        "cardContents": [
          {
            "title": "Card #1",
            "description": "The description for card #1",
            "suggestions": [
              {
                "reply": {
                  "text": "Card #1",
                  "postbackData": "card_1"
                }
              }
            ],
            "media": {
              "height": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg",
                "forceRefresh": false
              }
            }
          },
          {
            "title": "Card #2",
            "description": "The description for card #2",
            "suggestions": [
              {
                "reply": {
                  "text": "Card #2",
                  "postbackData": "card_2"
                }
              }
            ],
            "media": {
              "height": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg",
                "forceRefresh": false
              }
            }
          }
        ]
      }
    }
  }
}'

Node.js

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

// Images for the carousel cards
let card1Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg';
let card2Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg';

// Define the card contents for a carousel with two cards, each with one suggested reply
let cardContents = [
   {
      title: 'Card #1',
      description: 'The description for card #1',
      suggestions: [
         {
            reply: {
               text: 'Card #1',
               postbackData: 'card_1',
            }
         }
      ],
      media: {
         height: 'MEDIUM',
         contentInfo: {
            fileUrl: card1Image,
            forceRefresh: false,
         },
      },
   },
   {
      title: 'Card #2',
      description: 'The description for card #2',
      suggestions: [
         {
            reply: {
               text: 'Card #2',
               postbackData: 'card_2',
            }
         }
      ],
      media: {
         height: 'MEDIUM',
         contentInfo: {
            fileUrl: card2Image,
            forceRefresh: false,
         },
      },
   },
];

// Definition of carousel card
let params = {
   msisdn: '[phone]',
   cardContents: cardContents,
};

// Send the device the carousel card defined above
rbmApiHelper.sendCarouselCard(params, function(response) {
   console.log(response);
});

此代码摘自 RBM 示例代理。

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.cards.CardOrientation;
import com.google.rbm.cards.CardWidth;
import com.google.rbm.cards.MediaHeight;
import com.google.rbm.RbmApiHelper;
import com.google.rbm.SuggestionHelper;
…

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

            List cardContents = new ArrayList();

            // Images for the carousel cards
            String card1Image = "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg";

            // Create suggestions for first carousel card
            List card1Suggestions = new ArrayList();
            card1Suggestions.add(
                new SuggestionHelper("Card #1", "card_1"));

            cardContents.add(
                new StandaloneCardHelper(
                    "Card #1",
                    "The description for card #1",
                    card1Image,
                    card1Suggestions)
                    .getCardContent(MediaHeight.SHORT)
            );

            // Images for the carousel cards
            String card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg";

            // Create suggestions for second carousel card
            List card2Suggestions = new ArrayList();
            card2Suggestions.add(
                new SuggestionHelper("Card #2", "card_2"));

            cardContents.add(
                new StandaloneCardHelper(
                    "Card #2",
                    "The description for card #2",
                    card2Image,
                    card2Suggestions)
                    .getCardContent(MediaHeight.SHORT)
            );

            // Send the carousel to the user
            rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "[phone]");
        } catch(Exception e) {
            e.printStackTrace();
        }

此代码摘自 RBM 示例代理。

Python

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

# Images for the carousel cards
card_image_1 = 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg';
card_image_2 = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg';

# Suggested replies to be used in the cards
suggestions1 = [
      messages.SuggestedReply('Card #1', 'reply:card_1')
]

suggestions2 = [
      messages.SuggestedReply('Card #2', 'reply:card_2')
]

# Define the card contents for a carousel with two cards,
# each with one suggested reply
card_contents = []
card_contents.append(messages.CardContent('Card #1',
                                          'The description for card #1',
                                          card_image_1,
                                          'MEDIUM',
                                          suggestions1))

card_contents.append(messages.CardContent('Card #2',
                                          'The description for card #2',
                                          card_image_2,
                                          'MEDIUM',
                                          suggestions2))

# Send the device the carousel card defined above
carousel_card = messages.CarouselCard('MEDIUM', card_contents)
cluster = messages.MessageCluster().append_message(carousel_card)
cluster.send_to_msisdn('[phone]')

此代码摘自 RBM 示例代理。

C#

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
using RCSBusinessMessaging.Cards;
…

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

// Image references to be used in the carousel cards
string card1Image = "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg";
string card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg";

// Suggestion chip lists to be used in carousel cards
List<Suggestion> suggestions1 = new List<Suggestion>
{
   new SuggestionHelper("Card #1", "card_1").SuggestedReply()
};

List<Suggestion> suggestions2 = new List<Suggestion>
{
   new SuggestionHelper("Card #2", "card_2").SuggestedReply()
};

// Create the card content for the carousel
List<CardContent> cardContents = new List<CardContent>
{
   // Add items as card content
   new StandaloneCardHelper(
                    "Card #1",
                    "The description for card #1",
                    card1Image,
                    suggestions1).GetCardContent(),
   new StandaloneCardHelper(
                    "Card #2",
                    "The description for card #2",
                    card2Image,
                    suggestions2).GetCardContent()
};

// Send the carousel to the user
rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);

此代码摘自 RBM 示例代理。