Capability checks

To check if a user's device is RCS-enabled and capable of communicating with an RBM agent, you can request the device's capabilities. Identifying which features a device supports, if any, allows your agent to tailor the conversation to the device's capabilities and avoid presenting interactions that are difficult or impossible for the user to complete.

If a user's device isn't capable of receiving RCS messages at all, you can communicate with the user through other services, such as SMS.

Send a capability check

The following code sends a capability check and waits for a response. For formatting and value options, see 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);
});

This code is an excerpt from an RBM sample agent.

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]");

This code is an excerpt from an RBM sample agent.

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]')

This code is an excerpt from an RBM sample agent.

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]");

This code is an excerpt from an RBM sample agent.

Capability response

After running a capability check, the RBM platform returns a JSON-formatted list of features that the specified device supports.

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

If you send a capability check to a user who isn't reachable by RBM—for example, if their device doesn't support RCS—the RBM platform returns a 404 error.

If you send a capability check to an RCS user on a network where your agent is not yet launched, the RBM platform returns a 403 error.

Bulk capability checks

To estimate the number of RBM-reachable users, do a bulk capability check. Bulk checks indicate whether a phone number is reachable but not which features a phone number supports.

You can specify up to 10,000 phone numbers per bulk capability check. To check more numbers, perform multiple checks. Use the Bulk Capability Check Script to use CSV files as an input format.

Bulk capability checks have a maximum of 600 queries per minute (QPM).

Note: Testers are considered non-reachable users in the context of bulk capability checks.

Bulk capability checks return a list of the numbers your agent can reach on carriers where it is launched, as well as estimates for the total number of reachable users across all carriers. See Bulk capability check response.

Estimate total reachable users

While bulk check responses include a list of phone numbers that are immediately reachable on your agent's launched carriers (reachableUsers), responses also include two values that can help you estimate the total number of reachable users across all carriers.

When your agent performs a bulk capability check of more than 500 phone numbers, RBM randomly samples ~75% of those numbers to check all carriers (reported in totalRandomSampleUserCount). RBM also returns the count of RBM-reachable numbers from the random sample, regardless of carrier launch status (reachableRandomSampleUserCount). By dividing reachableRandomSampleUserCount by totalRandomSampleUserCount, you can estimate the percentage of numbers your agent could reach if it were launched on all carriers.

For example, if you specify 5,000 phone numbers in the bulk capability check, and RBM randomly samples ~75% of the specified numbers, totalRandomSampleUserCount may be 3750. If reachableRandomSampleUserCount is 3000, then 80% of sampled numbers were reachable.

Testing random samples can lead to variances in percentages. To account for the effects of random sampling, run bulk capability checks with larger amounts of phone numbers. You might also perform checks with the same batches of numbers multiple times and then average the results to normalize the random sampling behavior.

Send a bulk capability check

The following code sends a bulk capability check and waits for a response. For formatting and value options, see users.batchGet.

Phone numbers must be in E.164 format (for example, "[phone]"), and the list must contain 500 to 10,000 unique phone numbers.

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);
});

This code uses the RBM sample agent.

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]"));

This code uses the RBM sample agent.

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]'])

This code uses the RBM sample agent.

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]"}));

This code uses the RBM sample agent.

Bulk capability check response

After running a bulk capability check, RBM returns a JSON-formatted response.

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

Field	Description
reachableUsers	A list of reachable users on the agent's launched carriers.
totalRandomSampleUserCount	The count of a random sample of specified numbers. Typically ~75% of the specified numbers.
reachableRandomSampleUserCount	The count of numbers from the random sample that are RBM-reachable across all carriers, regardless of which carriers the agent is launched on.

Tool: Bulk Capability Check Script

The Buck Capability Check Script (Sign in to download) performs bulk capability checks using CSV files as input and output formats. The script parses the CSV file of MSISDNs and uses the RBM SDK to check the capabilities of every listed device.

A virtual machine of 2 CPUs and 4GB of RAM running the script with 500 threads can reach approximately 1K QPS, but overall QPS depends on the machine used, the country of the devices, the regional configuration of your agent, and the API endpoint used.

Prerequisites

Before using the tool to perform a bulk capability check, get the following:

• The path to a CSV file with MSISDNs to perform capability checks on
• The path to your agent's service account key on your development machine

Additionally, you need the following software installed on your development machine:

• Apache Maven 3.3.9 or greater
• Java 8

Set up

1. On your development machine, download and extract the Bulk Capability Check Script (Sign in to download).
2. Follow the steps in the README.

Run a bulk check

1. In a terminal, navigate to the script's root directory.

2. Run the following commands:

   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"

   Replace variables with values you've identified.

   Replace	With	Example
   AGENT_ID	ID of the RCS Business Messaging agent	welcome-bot
   INPUT_FILE	The path to the input CSV file.	input.csv
   OUTPUT_FILE	The path to the output CSV file.	output.csv
   NUM_OF_THREADS	The number of threads to dedicate to capability checks.	500
   START_INDEX	Optional. The value in the CSV file to begin running checks against.	5
   END_INDEX	Optional. The value in the CSV file to end checks after.	500

3. When the script completes, open the output CSV file to view the results.