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 at all, 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" \ -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('../libs/rbm_api_helper'); // Send a capability check to the device rbmApiHelper.checkCapability('+12223334444', 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.samples.lib.RbmApiHelper; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Check the capabilities of the device boolean capability = rbmApiHelper.getCapability("+12223334444");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('+12223334444')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("+12223334444");This code is an excerpt from an RBM sample agent.
Alternatively, you can send an asynchronous capability check and receive a
response through Google Cloud Pub/Sub. For formatting and value options, see
phones.capability.requestCapabilityCallback
.
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, such as if
their device doesn't support RCS, the RBM Platform returns a 404
error.
If you send a capability check to a user who is 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 includes 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 respond with the specified numbers that are reachable by the agent, and estimates for the amount of RBM-reachable numbers across all carriers. See Bulk capability check response.
Estimate total reachable users
While bulk checks responses include a list of phone numbers
that are immediately reachable on your agent's current 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 across 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 was launched on
all carriers.
For example, if you specified 5,000 phone numbers in the bulk capability check,
and RBM randomly samples ~75% of 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 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, "+12223334444".
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/users:batchGet \ -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('../libs/rbm_api_helper'); // Specify phone numbers let phoneNumbers = ['+12223334444', '+12223334444']; // 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.samples.lib.RbmApiHelper; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Perform a bulk capability check BatchGetUsersResponse batchGetUsersResponse = rbmApiHelper.getUsers(Arrays.asList("+12223334444", "+12223334444"));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(['+12223334444', '+12223334444'])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 ListThis code uses the RBM sample agent.({"+12223334444", "+12223334444"}));
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 users reachable by the agent on the agent's current 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 the agent's current launched carriers. |
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 you perform a bulk capability check, you need the following items:
- 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
- On your development machine, download and extract the Bulk Capability Check Script (Sign in to download).
- Navigate to the script's root directory.
- Rename the service account key to "rbm-agent-service-account-credentials.json" and move the service account key into the "src/main/resources" directory.
Run a bulk check
- In a terminal, navigate to the script's root directory.
Run the following commands:
export MAVEN_OPTS="-Xms1024m -Xmx3000m"
mvn compile && mvn exec:java -Dexec.args="INPUT_FILE OUTPUT_FILE NUM_OF_THREADS START_INDEX END_INDEX"
Replace variables with values you've identified.
Replace With Example 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
When the script completes, open the output CSV file to view the results.