发送消息

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

在某些情况下,RCS for Business 平台会返回错误,以帮助您管理消息传递:

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

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

收件人已离线

如果收件人处于离线状态,RCS for Business 平台仍会接受要递送的消息。您会收到 200 OK 响应,RCS for Business 平台会保留该消息,并在 30 天内尝试重新递送。无需让 RCS for Business 重新发送消息。

RCS for Business 会在消息提交 30 天后删除所有未送达的消息。

根据代理的使用场景,您可能需要在 30 天超时之前撤消未送达的消息。撤消功能可以防止离线用户在重新上线时收到过时的消息。您可以通过多种方式撤销消息:

设置邮件失效日期

您的代理发送的消息是否具有时效性?例如,动态密码仅在短时间内有效。限时优惠到期。预约提醒在预约日期过后便不再相关。为确保消息的时效性和相关性,请设置消息过期时间。这可以防止离线用户在重新上线时收到过时的内容。过期也是调用后备消息策略的好时机,这样用户就能及时获得所需信息。

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

  • expireTime:消息过期的确切时间(世界协调时间 [UTC])。
  • ttl(存留时间):消息过期前的时间。

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

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

ttl 和 expireTime 的最小值为消息提交后六秒。

有关设置邮件失效日期的建议

  • 对于身份验证(动态密码)消息:将 ttl 设置为消息提交后 15 秒或更长时间,以显著降低递送和撤消竞态条件的发生几率。

  • 对于事务性和促销性消息:请设置更长的过期时间(至少 60 秒,或几分钟到几小时,具体取决于用例),因为设备需要额外的时间来扫描消息和下载或处理富媒体内容,并且用户可能会遇到短暂的连接中断(例如,在电梯或隧道中)。

消息的存留时间 (TTL)

为 RCS for Business 消息设置 TTL 时,您需要指定该消息应被视为有效且可递送的时长。如果消息未在此 TTL 期限内成功递送到用户的设备,RCS for Business 平台会自动尝试撤消该消息。

当您发起消息撤销时,您会请求 RCS for Business 平台停止尝试递送该特定消息。不过,此操作只会影响未来的递送尝试。如果用户的设备已成功检索到消息,则消息正在处理中,RCS for Business 平台无法从用户的设备中撤消消息。

以下是关于通知的预期情况:

  • 在 TTL 内递送的消息:如果用户的设备在 TTL 到期之前上线并收到消息,您会收到 DELIVERED 通知。由于邮件已成功递送,因此系统不会发送撤销通知。这是最常见且符合预期的情况。

  • 消息在 TTL 到期前未送达:如果 TTL 在消息到达用户设备之前到期(例如,设备处于离线状态),RCS for Business 平台会尝试撤消该消息。您会收到 TTL_EXPIRATION_REVOKED 通知,表明邮件已成功从递送队列中移除。在这种情况下,用户将不会收到消息。

关于处理极端情形的建议

我们的系统会并行处理 RCS for Business 消息递送和 TTL 到期。因此,在极少数情况下,您可能会遇到通知时间不符合预期的情况。例如,您可能会同时收到传送通知和 TTL 通知,也可能两者都收不到。

以下是我们针对处理 RCS for Business 消息通知的建议:

  • DELIVERED 通知:如果您收到邮件的 DELIVERED 通知,则表示邮件已送达用户。您可以放心地忽略该特定消息的所有后续 TTL 通知。

  • TTL_EXPIRATION_REVOKED 通知:如果您收到状态为 TTL_EXPIRATION_REVOKED 的 TTL 通知,则表示 RCS for Business 系统已停止尝试递送该特定消息。您应将此消息视为未送达,并根据需要继续执行后备策略。

  • 具有任何其他状态的 TTL 通知:如果您收到具有任何其他状态的 TTL 通知,则表示撤消尝试没有结果。

    • 对于重要消息(例如动态密码 [OTP]),请启动备用方法。
    • 对于非关键消息,请决定是否启动回退。
  • 无通知:在极少数极端情况下,系统可能无法发送 TTL 通知,客户端也可能无法生成递送通知。这种情况极为罕见。

设置消息流量类型

RBM API 包含一个 messageTrafficType 字段,用于对消息进行分类。虽然智能体应用场景仍会定义智能体行为和适用的业务规则,但 messageTrafficType 允许对消息内容进行更详细的分类。最终,这使得单个代理能够处理多个用例。目前,现有代理用例或业务规则不会受到任何影响。

此字段为选填字段,但建议您现在就进行设置,以免该字段变为必填字段时收到错误消息。

如需设置消息流量类型,请根据每条消息的内容为其分配适当的 messageTrafficType。下表列出了支持的流量类型及其预期的代理用例。此映射是关于预期用法的建议指南,而不是 API 目前强制执行的限制。

流量类型 消息内容 推荐的代理使用场景
AUTHENTICATION 用于身份验证消息。 动态密码
TRANSACTION 用于发送与用户现有服务或产品相关的消息。例如:确认信息、付款收据或预订详情。 事务性或多用途
PROMOTION 用于发送推广内容,例如优惠、折扣、公告或其他推广内容。 促销或多次使用
SERVICEREQUEST 用于发送用户明确请求的服务相关消息。 动态密码、事务型、促销型或多用途
ACKNOWLEDGEMENT 用于确认用户操作(特别是退订请求)的消息。此邮件旨在确认我们已收到用户的请求,并且正在处理。 动态密码、事务型、促销型或多用途

如果未设置流量类型,系统会为代理的用例分配默认类型。

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

多用途代理没有默认流量类型。您应根据每条消息的内容明确设置其流量类型。如果您不替换 MESSAGE_TRAFFIC_TYPE_UNSPECIFIED 值,消息仍会被接受并传送,但不会有特定的流量类型分类。

邮件大小限制

整个字符串化 AgentMessage 的大小上限为 250 KB。消息的文本部分有其自己的 3072 个字符的限制。

为防止用户产生意外的数据流量消耗,通过 RCS for Business 发送的文件大小上限为 100 MiB,并且单条 RCS for Business 消息中所有媒体和 PDF 附件的总大小不得超过 100 MiB。(1 MiB = 1,048,576 字节)。如需了解详情,请参阅媒体和 PDF 文件。

文本

最简单的消息由文本组成。文字消息最适合用于传达无需视觉效果、复杂互动或响应的信息。

示例

以下代码会发送一条纯文本消息。如需了解格式设置和值选项,请参阅 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: '+12223334444',
};

// 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!",
      "+12223334444"
   );
} 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('+12223334444')
此代码摘自 RBM 示例代理。

C#

using RCSBusinessMessaging;
…

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
);
此代码摘自 RBM 示例代理。

Basic Message content - conversion of SMS

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

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

在框中输入一些文字,以检查其长度:

RCS 客户端可以实现链接预览。如果纯文本 RCS for Business 消息包含带有 openGraph 标记的网站网址,客户端可以生成预览(图片、标题等),从而提供更丰富的体验。例如,请参阅包含网址预览的基本消息。

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

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

您可以使用 RCS for Business 发送动态密码 (OTP),以便通过 SMS Retriever API 自动验证用户。没有专门用于读取通过 RCS for Business 收到的动态密码的 API。

Android 上的运作方式

对于已向 SMS Retriever API 注册的 Android 应用,该 API 会监听格式正确的 RCS for Business 消息。此消息必须同时包含动态密码和用于标识应用的唯一哈希。

当收到格式正确的 RCS for Business 消息时,SMS Retriever API 会像处理短信动态密码一样处理该消息。哈希值与您的应用匹配后,系统会提取动态密码并将其转发到您的应用,以便自动验证用户身份。

  • 用于用户验证的 RCS for Business 短信示例:Your code is <OTP><app hash>.
  • 示例:Your code is 123456 M8tue43FGT.

如需详细了解短信检索器和相关 API,请参阅短信检索器文档。 如需详细了解已注册 SMS Retriever API 的应用中的自动用户验证,请参阅此流程图。

iOS 上的运作方式

对于 iOS,系统内置的动态密码处理功能会自动检测并建议 RCS for Business 动态密码,以便自动填充,就像短信动态密码一样。iOS 应用无需进行特定的 API 集成即可读取动态密码。

媒体和 PDF 文件

当您发送包含图片、视频、音频或 PDF 文件的消息时,您的代理必须提供该内容的公开网址,或直接上传该文件。

可发送的文件大小上限为 100 MiB,单条消息中所有媒体和 PDF 附件的总大小不得超过 100 MiB。

媒体压缩和转码

RCS for Business 平台会在发送媒体文件(例如图片和视频)之前自动对其进行转码和压缩,以确保它们能够快速加载,并在不同的网络和设备上正常运行。

压缩取决于输入媒体的质量,而不是严格取决于文件大小限制。这意味着,即使文件大小远低于 100 MiB 的上限,也可以进行压缩。转码标准会不断变化,因此没有固定的文件大小限制来决定何时绕过转码。尝试不同的媒体格式、尺寸和压缩率,找到适合载荷的最佳平衡点。

缩略图规范

对于媒体文件,您还可以指定缩略图,让用户在点击内容之前先预览内容。对于音频文件,默认音频 widget 会用作占位符。

  • 缩略图的文件大小上限为 100 kB。为提供最佳用户体验,我们建议将其大小控制在 50 kB 或以下。
  • 缩略图的宽高比应与原始文件的宽高比一致。

缓存和网址管理

RCS for Business 平台会将文件缓存 60 天,API 会返回一个文件 ID,您的代理可以在发送给用户的消息中包含该 ID。60 天后,RCS for Business 会从缓存中移除文件。

按网址指定文件时,最佳做法是将 contentMessage.forceRefresh 设置为 false。将 contentMessage.forceRefresh 设置为 true 会强制 RCS for Business 从指定网址提取新内容,即使网址内容已缓存也是如此,这会增加向用户递送消息的时间。

文件网址示例

以下代码会发送图片。如需了解格式设置和值选项,请参阅 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: '+12223334444',
};

// 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, "+12223334444");
} 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('+12223334444')
此代码摘自 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, "+12223334444");
此代码摘自 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"
    }
  }
}'

支持的媒体类型

RCS for Business 支持以下媒体类型。对于缩略图,仅支持 image/jpeg、image/jpg、image/gif 和 image/png。

媒体类型 文档类型 扩展程序 可与复合信息卡搭配使用
application/ogg OGG 音频 .ogx 否
application/pdf PDF .pdf 是(仅适用于印度的 Google 信息)
audio/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 是
video/webm WEBM 视频 .webm 是

建议

您的代理会在建议内容信息条列表或复合信息卡中发送建议(回复建议和操作建议)。

回复建议

回复建议通过提供代理知道如何做出反应的回复,引导用户完成对话。

当用户点按回复建议时,您的代理会收到包含回复文本和回传数据的事件。载荷最多包含 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: '+12223334444',
   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!",
      "+12223334444",
      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('+12223334444')
此代码摘自 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!",
    "+12223334444",
   suggestions
);
此代码摘自 RBM 示例代理。

操作建议

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

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

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

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

建议显示

显示建议的方式有两种:

  • Persistent:在消息气泡内显示的操作建议或回复建议,在整个对话过程中保持固定。
  • 瞬时:在消息气泡外显示的建议,会在对话继续时消失。

支持的消息格式

  • 常驻建议:适用于独立短信和复合信息卡。
  • 临时建议:适用于独立短信、媒体消息和复合信息卡。

合并建议

您可以在同一条消息或复合信息卡中混合使用永久性建议和临时性建议。

  • 短信:默认情况下,建议是临时性的。如需让它们留在气泡内,您必须将其配置为永久性。
  • 复合信息卡:默认情况下,这些卡最多支持四个常驻建议。 然后,您可以在卡片下方以“条状标签列表”的形式添加临时建议。

建议时间限制

一条短信最多支持 11 条建议。您添加的任何永久性建议都会计入此总数上限。例如,如果您添加了 4 条常驻建议,则最多可以添加 7 条临时建议。

建议类型 限额 显示位置
永久性 最多 4 项 消息气泡内
暂时性 最多 11 个 气泡外(以条状标签形式)

字符数限制

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

操作建议中的网址透明度

为了建立用户信任,对于“打开网址”操作建议,系统会在建议按钮内将底层网址显示为第二行文字。这种一致的行为适用于独立短信、复合信息卡和轮播界面。

支持永久性建议的客户端

  • 支持:Google 信息(20260225.00 或更高版本)。
  • 不受支持:早于 20260225.00 的 Google 信息版本、iOS 和 Samsung Messages。

系统通知中的建议

当用户收到消息时,“Google 信息”会直接在 Android 系统通知中显示第一条符合条件的建议。用户可以点按此建议来发送回复或触发操作,而无需打开应用。

在设计消息时,请注意以下行为:

  • 顺序很重要:每条通知仅显示一条建议。为了最大限度地提高互动度,请将优先级最高的回复建议或操作放在建议列表中的首位。
  • 排除的操作:分享位置信息操作绝不会显示在系统通知中,用户必须打开对话才能分享其位置信息。

拨号

“拨号”操作会引导用户拨打代理指定的电话号码。 电话号码只能包含数字 (0-9)、加号 (+)、星号 (*) 和数字符号 (#)。支持 E.164 国际电话号码格式(例如 +14155555555),但并非必需。也就是说,+14155555555 和 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": "+15556667777"
          }
        }
      }
    ]
  }
}'

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: '+15556667777'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   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("+15556667777");

   // 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!",
      "+12223334444",
      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', '+15556667777')
]

# 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('+12223334444')
此代码摘自 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 = "+15556667777"
};

// 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!",
    "+12223334444",
    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: '+12223334444',
   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!",
      "+12223334444",
      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('+12223334444')
此代码摘自 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!",
    "+12223334444",
    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: '+12223334444',
   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!",
      "+12223334444",
      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('+12223334444')
此代码摘自 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!",
    "+12223334444",
    suggestions
);
此代码摘自 RBM 示例代理。

打开网址

“打开网址”操作可让您引导用户访问代理指定的网页。 默认情况下,网页会在用户的浏览器中打开。您还可以将网页设置为在 WebView 中打开。如需了解详情,请参阅使用 WebView 打开网址。

Google 信息独有功能

显示底层网址:为了提高 A2P 消息传递的透明度,Google 信息会在“打开网址”操作建议中显示底层网址。此变更会影响标准复合信息卡和复合信息卡轮播界面中的操作建议。

一个复合信息卡,其中显示了“查看网站”建议,下方显示了网址。
可见的底层网址

网页链接的应用图标显示:如果用户为网页配置了默认应用,系统会打开该应用,而不是浏览器或 WebView,并且建议按钮会显示该应用的图标。如需在 Google 信息中显示应用图标,您需要提供完整的直接网址。如果您使用短网址,系统会改为显示默认的“打开网址”图标。

建议按钮中的应用图标。
建议按钮中的应用图标
示例

以下代码会发送打开网址操作。如需了解格式设置和值选项,请参阅 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: '+12223334444',
   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!",
      "+12223334444",
      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('+12223334444')
此代码摘自 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!",
    "+12223334444",
    suggestions
);
此代码摘自 RBM 示例代理。

使用 WebView 打开网址

“使用 WebView 打开网址”操作会使用默认浏览器的渲染引擎在即时通讯应用中加载指定的网页。这样,用户无需离开 RCS for Business 对话即可与网页互动。如果用户的设备不支持 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!",
      "+12223334444",
      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: '+12223334444',
   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!",
      "+12223334444",
      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('+12223334444')
此代码摘自 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!",
    "+12223334444",
    suggestions
);
此代码摘自 RBM 示例代理。

建议内容信息条列表

您的代理会发送包含消息的建议内容信息条列表,以引导用户执行后续操作。仅当关联的消息位于对话底部时,才会显示条状标签列表。对话中的任何后续消息(来自用户或您的代理)都会覆盖条状标签列表。

列表中的条状标签是回复建议和操作建议。

信息条列表最多包含 11 个建议内容信息条,每个信息条标签最多可包含 25 个字符。

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

复合信息卡

复合信息卡将媒体、文字和互动式建议整合到一条消息中。它们非常适合呈现相关信息(例如,商品及其图片、名称和价格),并通过清晰的后续步骤(例如“查看详情”建议)引导用户。

复合信息卡可以包含以下内容:

这些字段都是可选的,但复合信息卡中必须至少包含字段 1-3 中的一个。

多个卡片可以一起在水平滚动的轮播界面中发送。

请注意,复合信息卡的总载荷为 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: '+12223334444',
   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, "+12223334444");
} 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('+12223334444')
此代码摘自 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, "+12223334444");
此代码摘自 RBM 示例代理。

轮播式复合信息卡

轮播界面将多个复合信息卡串联在一起,让用户可以比较各项内容并分别做出回应。

轮播界面最少可包含两张复合信息卡,最多可包含十张。轮播界面中的复合信息卡必须符合复合信息卡文档中所述的有关内容和高度的一般复合信息卡要求。 如需详细了解轮播界面布局和规范,请参阅轮播界面文档。

示例

以下代码会发送复合信息卡轮播界面。如需了解格式设置和值选项,请参阅 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/welcome-bot-sample-images/200.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/welcome-bot-sample-images/201.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/welcome-bot-sample-images/200.jpg';
let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.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: '+12223334444',
   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/welcome-bot-sample-images/200.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/welcome-bot-sample-images/201.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, "+12223334444");
        } 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/welcome-bot-sample-images/200.jpg';
card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.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('+12223334444')
此代码摘自 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/welcome-bot-sample-images/200.jpg";
string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.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 示例代理。