Updates: Check the release notes for new features and product updates.

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 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 List({"+12223334444", "+12223334444"}));
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 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:

Set up

  1. On your development machine, download and extract the Bulk Capability Check Script (Sign in to download).
  2. Navigate to the script's root directory.
  3. 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

  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="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

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