RCS Device Capability Check

A capability check can be performed to ascertain whether the target device supports RCS messaging features. There are currently two ways of performing a device capability check:

• Individual device check
• Bulk check

Individual Device Capability Check

The check is carried out via a GET request to the following URL:

https://api.nexmo.com/v1/channel-manager/rcs/agents/{vonage_id}/google/phones/{phone_number}/capabilities

There are two required path parameters:

• vonage_id. This is the sender ID for the RCS agent, and will be provided to you as part of the RCS set-up and onboarding process.
• phone_number. The number for the device which the capability check is for.

A Authorization header is required as part of the request. The value of the header should contain a valid JWT (JSON Web Token) in the format Bearer ${JWT}. The JWT can be created using the Application ID and Private Key from your Vonage Application with which the RCS Sender ID is associated. See Authentication for further information on creating JWTs.

See the Channel Manager API Specification for full technical details of this endpoint.

Example Request

Below is an example cURL request to the capability check endpoint:

curl --location 'https://api.nexmo.com/v1/channel-manager/rcs/agents/VonageBasic/google/phones/447900000000/capabilities' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...'

Responses

200 OK

If the device is RCS reachable, a 200 OK HTTP response will be received. The response body will contain an array of the RCS features supported by the device, for example:

{ 
  "features": 
   [ 
     "RICHCARD", 
     "RICHCARD_CAROUSEL", 
     "CREATE_CALENDAR_EVENT", 
     "DIAL_PHONE_NUMBER", 
     "OPEN_URL", 
     "SHARE_LOCATION", 
     "VIEW_LOCATION" 
   ] 
}

400 Bad Request

There are various circumstances where a 400 Bad Request HTTP response will be received, such as the Agent sender ID not being valid, or the phone number being checked having an invalid format.

403 Forbidden

If using a test agent and the number is not allow-listed for that agent, or using a live agent and the number is not connected to a supported network in the country in which the agent has been launched, a 403 Forbidden HTTP response will be received.

404 Not Found

If the device is not RCS reachable, a 404 Not Found HTTP response will be received.

Bulk Device Capability Check

The check is carried out via a POST request to the following URL:

https://api.nexmo.com/v1/channel-manager/rcs/agents/{vonage_id}/google/{operation}

There are two required path parameters:

• vonage_id. This is the sender ID for the RCS agent, and will be provided to you as part of the RCS set-up and onboarding process.
• operation. The operation to be performed by the RBM agent. In this case it is users:batchGet.

A Authorization header is required as part of the request. The value of the header should contain a valid JWT (JSON Web Token) in the format Bearer ${JWT}. The JWT can be created using the Application ID and Private Key from your Vonage Application with which the RCS Sender ID is associated. See Authentication for further information on creating JWTs.

A Content-Type header is required as part of the request. The value of the header should be application/json.

The request should contain a JSON body, which has one property: users. This is an array of strings which represent the phone numbers to be sampled during the bulk check.

Unlike the individual capability check, the bulk check does not return a list of supported features. The type of data returned will depend on the volume of numbers submitted in the users array.

• For 500 numbers of less, the reponse will contain an array of reachableUsers.
• For more than 500 numbers,the response returns the results of sampling a selection of the numbers provided and includes the count of the numbers that were sampled (totalRandomSampleUserCount) and the number of phone numbers within that sample which are reachable via RCS messaging (reachableRandomSampleUserCount).

See the Channel Manager API Specification for full technical details of this endpoint.

Example Request

Below is an example cURL request to the capability bulk check endpoint:

curl -X POST https://api.nexmo.com/v1/channel-manager/rcs/agents/VonageBasic/google/users:batchGet \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-d '{
  "users": [
    "34613994828",
    "34613994829"
  ]
}'

Responses

200 OK

For successful requests where the users array contains 500 numbers or less, the response will contain an array of reachable users which will be a sub-set of the numbers submitted for checking:

{ 
  "reachableUsers": [ 
     "34613994828",
     "34613994829" 
   ] 
}

For successful requests where the users array contains more than 500 numbers, the response will contain the results of sampling the provided numbers:

{ 
  "totalRandomSampleUserCount": 632,
  "reachableRandomSampleUserCount": 324
}

If none of the numbers submitted are RCS reachable, then an empty object will be received in the response:

{}

400 Bad Request

There are various circumstances where a 400 Bad Request HTTP response will be received, such as the Agent sender ID not being valid, or one or more of the phone numbers being checked having an invalid format.