功能检查

如需检查用户的设备是否支持 RCS 且能够与 RBM 代理通信，您可以请求设备的各项功能。了解设备支持哪些功能（如果有），有助于您的代理根据设备的功能定制对话，避免呈现用户难以完成或无法完成的互动。

如果用户的设备根本无法接收 RCS 消息，您可以通过其他服务（例如短信/彩信）与用户通信。

检查设备功能

以下代码会发送功能检查并等待响应。如需了解 格式和值选项，请参阅 getCapabilities。

cURL

curl -X GET "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/capabilities?requestId=REQUEST_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`"

Node.js

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

// Send a capability check to the device
rbmApiHelper.checkCapability('[phone]', function(response) {
   // Print capabilities of the device
   console.log(response);
});

此代码段摘自 RBM 示例代理。

Java

import com.google.rbm.RbmApiHelper;
…

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

// Check the capabilities of the device
boolean capability = rbmApiHelper.getCapability("[phone]");

此代码段摘自 RBM 示例代理。

Python

# Reference to RBM Python client helper
from rcs_business_messaging import rbm_service

# Send the tester invite to a device
response = rbm_service.make_cap_request('[phone]')

此代码段摘自 RBM 示例代理。

C#

using RCSBusinessMessaging;
…

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

// Register the device as a tester
Capabilities capabilities = rbmApiHelper.GetCapability("[phone]");

此代码段摘自 RBM 示例代理。

功能响应

运行功能检查后，RBM 平台会返回 JSON 格式的列表 ，其中列出了指定设备支持的功能 。

{
  "features": [
    "RICHCARD_STANDALONE",
    "RICHCARD_CAROUSEL",
    "ACTION_CREATE_CALENDAR_EVENT",
    "ACTION_DIAL",
    "ACTION_OPEN_URL",
    "ACTION_SHARE_LOCATION",
    "ACTION_VIEW_LOCATION",
    "ACTION_OPEN_URL_IN_WEBVIEW",
    "PDF_IN_RICH_CARDS"
  ]
}

该请求会返回响应或错误。

仅当 MSISDN（电话号码）在过去 31 天内连接到 RCS 服务时，才会返回成功响应 。这意味着用户的设备在该时间范围内已向我们的 RCS 服务器签到。在线且支持 RCS 的设备平均每 1-4 小时签到一次。

如果用户将其 SIM 卡移至其他支持 RCS 的设备，系统会移除之前的设备关联，并创建一个新的关联，从而更新 RCS 服务中设备的功能。

如果 SIM 卡插入到运营商或制造商停用了 RCS 的设备中，或者 SIM 卡仍处于未使用状态，RCS 服务仍会尝试将消息传递到之前关联的设备，最长可达 31 天。

以下情况会导致 404 错误：

• RBM 无法联系到用户，例如，用户的设备不支持 RCS。

• 用户支持 RCS，但您的代理未在其移动网络上启动。

离线排队

消息最多会排队 31 天，并在设备重新上线时传递。这意味着，即使设备离线时间较长（最长 31 天），只要 MSISDN 在过去 31 天内连接到 RCS 服务，排队的消息仍会在重新连接后传递。

批量功能检查

如需估算可联系到的 RCS for Business 用户数量，请执行批量功能检查。批量检查会指明电话号码是否可联系到，但不会指明电话号码支持哪些 功能 。

对于每次批量功能检查，您必须提供来自同一地理区域的 500-10,000 个唯一电话号码。如需检查更多号码，请执行多次检查。您每分钟最多可以拨打 600 个电话。使用 批量功能检查脚本，以 CSV 文件作为输入格式。 批量检查会从功能缓存中读取数据，该缓存由客户端使用 RCS 自行更新。代理不会直接请求每台设备的功能。因此，结果可能不是最新的。

重要提示： 必须使用区域端点才能使用 users.batchGet 方法。 请求必须包含来自单个区域的电话号码，以避免出现 400 Bad Request 错误。

注意： 测试人员 在批量功能检查的上下文中被视为无法联系到的用户。

批量功能检查会返回一个列表，其中列出了您的代理在其启动的运营商处可以联系到的号码，以及所有运营商中可联系到的用户总数的估算值。请参阅批量功能检查响应。

估算可联系到的用户总数

虽然批量检查 响应 包含一个列表，其中列出了您的代理在其启动的运营商处可以立即联系到的电话号码 (reachableUsers)，但响应还包含两个值，可帮助您估算 所有运营商中可联系到的用户总数。

运作方式

当您的代理执行批量功能检查时，RBM 会随机抽取约 75% 的号码来检查所有运营商（在 totalRandomSampleUserCount 中报告）。无论代理在哪些运营商上启动，RBM 还会返回随机抽取的样本中 RBM 可联系到的号码数 (reachableRandomSampleUserCount)。通过将 reachableRandomSampleUserCount 除以 totalRandomSampleUserCount，您可以估算如果您的代理在所有运营商上启动，则可以联系到的号码百分比。

例如，如果您在批量功能检查中指定了 5,000 个电话号码，RBM 会随机抽取约 75% 的指定号码，则 totalRandomSampleUserCount 可能为 3750。如果 reachableRandomSampleUserCount 为 3000，则 80% 的抽样号码可联系到。

考虑随机抽样

测试随机样本可能会导致百分比出现差异。如需考虑随机抽样的影响，请使用大量电话号码运行批量功能检查。您还可以使用相同的号码批次执行多次检查，然后对结果取平均值，以规范随机抽样行为。

发送批量功能检查

以下代码会发送批量功能检查并等待响应。如需了解 格式和值选项，请参阅 users.batchGet。

电话号码必须采用 E.164 格式（例如“[phone]”），并且列表必须包含 500 到 10,000 个唯一电话号码。

重要提示： 如果批次包含来自多个区域的号码，请求将 失败并显示 400 Bad Request 错误。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/users:batchGet?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 '{
  "users": [
    "PHONE_NUMBER",
  ]
}'

Node.js

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

// Specify phone numbers
let phoneNumbers = ['[phone]', '[phone]'];

// Perform a bulk capability check
rbmApiHelper.getUsers(phone_numbers, function(response) {
   // Print the bulk capability check response
   console.log(response);
});

此代码使用 RBM 示例 代理。

Java

import com.google.rbm.RbmApiHelper;
…

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

// Perform a bulk capability check
BatchGetUsersResponse batchGetUsersResponse = rbmApiHelper.getUsers(Arrays.asList("[phone]", "[phone]"));

此代码使用 RBM 示例 代理。

Python

# Reference to RBM Python client helper
from rcs_business_messaging import rbm_service

# Perform a bulk capability check
response = rbm_service.make_batch_cap_request(['[phone]', '[phone]'])

此代码使用 RBM 示例代理。

C#

using RCSBusinessMessaging;
…

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

// Perform a bulk capability check
BatchGetUsersResponse batchGetUsersResponse = rbmApiHelper.GetUsers(new List({"[phone]", "[phone]"}));

此代码使用 RBM 示例 代理。

批量功能检查响应

运行批量功能检查后，RBM 会返回 JSON 格式的响应。

{
  "reachableUsers": [
    "PHONE_NUMBER"
  ],
  "totalRandomSampleUserCount": "COUNT_OF_SAMPLE",
  "reachableRandomSampleUserCount": "REACHABLE_FROM_SAMPLE"
}

字段	说明
reachableUsers	代理在其启动的运营商处可以联系到的用户列表。
totalRandomSampleUserCount	随机抽取的指定号码数。通常约为指定号码的 75%。
reachableRandomSampleUserCount	随机抽取的样本中 RBM 可在所有运营商处联系到的号码数，无论代理在哪些运营商上启动。此计数用于大致估算所有运营商中可联系到的用户总数。
reachableUsersMap	仅限输出。运营商 ID 到该运营商处可联系到的用户列表的映射。此字段仅针对美国电话号码填充。

工具：批量功能检查脚本

批量功能检查脚本 Buck Capability Check Script (Sign in to download) 使用 CSV 文件作为输入和输出格式执行批量功能检查。 该脚本会解析 MSISDN 的 CSV 文件，并使用 RBM SDK 检查每个列出的设备的功能。

一台具有 2 个 CPU 和 4GB RAM 的虚拟机以 500 个线程运行该脚本，每秒查询数 (QPS) 大约可以达到 1K，但总体 QPS 取决于所使用的机器、设备的国家/地区、代理的区域配置以及所使用的 API 端点。

前提条件

在使用该工具执行批量功能检查之前，请获取以下内容：

• 包含要执行功能检查的 MSISDN 的 CSV 文件的路径
• 开发机器上代理的服务账号密钥的路径

此外，您还需要在开发机器上安装以下软件：

• Apache Maven 3.3.9 或更高版本
• Java 8

设置

如需设置开发机器以进行批量功能检查，请执行以下操作：

1. 下载并解压缩 Bulk Capability Check Script (Sign in to download).
2. 按照自述文件中的步骤操作。

运行批量功能检查

如需运行批量检查，请按以下步骤操作：

1. 在终端中，导航到脚本的根目录。

2. 运行以下命令：

   export MAVEN_OPTS="-Xms1024m -Xmx3000m"
   mvn compile && mvn exec:java -Dexec.args="AGENT_ID INPUT_FILE OUTPUT_FILE NUM_OF_THREADS START_INDEX END_INDEX"

   将变量替换为您已确定的值。

   替换	为	示例
   AGENT_ID	RCS for Business 商家智能体的 ID。	welcome-bot
   INPUT_FILE	输入 CSV 文件的路径。	input.csv
   OUTPUT_FILE	输出 CSV 文件的路径。	output.csv
   NUM_OF_THREADS	专用于功能检查的线程数。	500
   START_INDEX	可选。CSV 文件中开始运行检查的值。	5
   END_INDEX	可选。CSV 文件中在之后结束检查的值。	500

3. 脚本完成后，打开输出 CSV 文件以查看结果。