Verify RCS capability of recipients

Not all mobile devices support RCS messaging. Even supported devices might have RCS disabled.

Before sending an RCS message to an end user, you can check whether their phone number can receive RCS messages. If it cannot receive RCS messages, you can use a different channel to communicate with the end user.

This tutorial explains how to use API to identify which of the phone numbers in a list can receive RCS messages from the specified sender.

Products and channels

Prerequisites

Infobip account with RCS enabled.

If you do not have an account, create a free trial account and select RCS channel on the welcome screen.
Infobip API key with the following scope:

rcs:message:send

For information about creating an API key with the required scope, refer to API authorization.
An HTTP client. This tutorial uses curl. Alternatively, you can choose the official Infobip SDK for the required programming language.
RCS agent or sender must be configured and launched on the mobile network/carrier in which you want to check the RCS capability of destination phone numbers.

If the agent/sender is not launched on the network, the capability check request always returns a negative status for the destination phone numbers.

To launch the sender or to configure a custom RCS sender, contact your Infobip account manager.
Capability checker must be enabled on your Infobip account. For more information, contact your Infobip account manager.
A destination phone number for which you want to check RCS support.

Process overview

Create an API request to check the capability of a list of phone numbers to receive RCS messages. Use one of the following endpoints:

Check RCS capability (opens in a new tab): You can check a maximum of 500 phone numbers in a single request. Refer to the detailed implementation steps.
Check RCS capability (asynchronous) (opens in a new tab): This request runs asynchronously. You can check a maximum of 10,000 phone numbers in a single request. Refer to the detailed implementation steps.

The response shows the capability statuses of each phone number individually.

Implementation steps

Check RCS capability

Create an API request (opens in a new tab) to send check the capability of RCS messaging.

curl -X POST https://api.infobip.com/rcs/2/capability-check/query  
-H 'Authorization: App {YOUR_API_KEY}'  
-H 'Content-Type: application/json' 

{
    "sender": "{YOUR_SENDER}",
    "phoneNumbers": [
    "{YOUR_DESTINATION_NUMBER1}",
    "{YOUR_DESTINATION_NUMBER2}"
    ]
}

Receive the results through the API response.

The response has a 200 status and contains the message ID and message status.

The message status is as follows:

ENABLED: The device has RCS capability and RCS is enabled in the device.
UNREACHABLE: The device does not have RCS capability.

curl -X POST https://api.infobip.com/rcs/2/capability-check/query

-H 'Authorization: App {YOUR_API_KEY}'\
-H 'Content-Type: application/json' \

{

    "capabilityCheckResults": [

    {
        "messageId": "749992b8-cacc-4a01-b366-4f10281f5c5c",
        "phoneNumber": "{YOUR_DESTINATION_NUMBER1}",
        "code": "ENABLED"
    },

    {
        "messageId": "2520f340-738d-415b-a9de-d772b43a513d",
        "phoneNumber": "YOUR_DESTINATION_NUMBER2",
        "code": "UNREACHABLE"
    }

    ]
}

Check RCS capability asynchronously

Create a subscription and notification profile through one of the following ways:
- Use the Subscriptions Management API (opens in a new tab).
- Use Infobip web interface (opens in a new tab). On the left-hand menu, go to Developer tools > Subscription management. For more information, refer to Subscriptions documentation.

Create an API request (opens in a new tab) to send check the capability of RCS messaging.

curl -X POST https://api.infobip.com/rcs/2/capability-check/notify  
-H 'Authorization: App {YOUR_API_KEY}'  
-H 'Content-Type: application/json'  

{
    "sender": "{YOUR_SENDER}",
    "phoneNumbers": [
    "{YOUR_DESTINATION_NUMBER1}",
    "{YOUR_DESTINATION_NUMBER2}"
    ],
 
    "notifyUrl": "The_URL_of_your_callback_server",
    "notifyContentType": "application/json"
}

Receive the results through the API response.

curl -X POST https://api.infobip.com/rcs/2/capability-check/notify
-H 'Authorization: App {YOUR_API_KEY}'\
-H 'Content-Type: application/json' \

{
    "bulkId": "822d0d0e-fd95-445c-b8d9-65e174cc00c5",
    "capabilityCheckRequestStates": [
    {
        "messageId": "26854ca9-4fb8-4173-8e2c-bcf11166cbde",
        "phoneNumber": "{YOUR_DESTINATION_NUMBER1}",
        "status": "PENDING_ENROUTE"
    },

    {
        "messageId": "2775dec6-e49a-4dfa-9459-064964817a7f",
        "phoneNumber": "{YOUR_DESTINATION_NUMBER2}",
         "status": "PENDING_ENROUTE"
    }
    ]
}

Receive the capability check result on your webhook:

POST: https://{yourDomain}/your/webhook/path

On your URL, you should receive a response that has a 200 status and contains a bulkId, message ID, phoneNumber, and message status.

The message status is as follows:

ENABLED – The device has RCS capability and RCS is enabled in the device.
UNREACHABLE – The device does not have RCS capability.

{
    "capabilityCheckResult": {
    "bulkId": "822d0d0e-fd95-445c-b8d9-65e174cc00c5",
    "messageId": "26854ca9-4fb8-4173-8e2c-bcf11166cbde",
    "phoneNumber": "{YOUR_DESTINATION_NUMBER1}",
    "code": "UNREACHABLE"
    }
}
{
    "capabilityCheckResult": {
    "bulkId": "822d0d0e-fd95-445c-b8d9-65e174cc00c5",
    "messageId": "2775dec6-e49a-4dfa-9459-064964817a7f",
    "phoneNumber": "{YOUR_DESTINATION_NUMBER2}",
    "code": "ENABLED"
    }
 }

Additional resources

RCS API reference (opens in a new tab) documentation.
RCS documentation.
Subscriptions Management API (opens in a new tab).
Subscriptions management documentation for the Infobip web interface.
Response status and error codes documentation.
Infobip SDK documentation.