Programmable Messaging RCS Onboarding Guide

See Regional Availability for a list of regions where RCS messages can be sent using Twilio Programmable Messaging, and any special requirements for each region.

Allow 2–4 weeks (or longer if launching in multiple regions) to complete the onboarding process after receiving RCS access. The following steps outline the process to set up and configure RCS messaging with Twilio.

Complete these steps before starting the RCS onboarding process.

• Create a Twilio Account.
• Review Regional Availability to ensure RCS compatibility in your messaging regions and understand any unique requirements.
• Review current limitations:
  • Public Beta supports text and media messaging. Rich-content capabilities aren't yet available.
  • Creating RCS Senders for client businesses as an ISV (Independent Software Vendor) isn't yet supported. ISVs can still request RCS access to start testing.
  • Conversations aren't yet supported.

• Familiarize yourself with Programmable Messaging concepts such as Messaging Services and the Message Resource, which are both used to send RCS messages.

First, request access to use RCS in Programmable Messaging. Complete the RCS request form with the required business and use case information. Twilio manually reviews the submission. The approval process duration can vary based on submission volume and the complexity of your request, but it typically takes a few days.

After your RCS access is granted, you will receive an email at the address provided in the request form with a link to begin RCS onboarding in the Twilio Console.

Next, create an RCS Sender in the Twilio Console. The RCS Sender represents both your messaging use case and the brand that is displayed to the recipient when you send an RCS message. RCS messages arrive from this named and verified sender instead of a phone number or alphanumeric sender. You can create multiple RCS Senders; however, they cannot be shared between Twilio Accounts.

After you create your RCS Sender in the Console, it is sent to both Twilio and Google RCS Business Messaging for approval. Twilio is a Google RCS Business Messaging partner, and you will not need to interact directly with Google during this process except to confirm your brand use via email in Step 3.

Navigate to the RCS Senders page in the Console to create your RCS Sender. During the creation process, you complete three sections: Profile Information, Test, and Compliance.

In this section, you construct your RCS Sender's branded profile. This profile is visible to recipients when you send RCS messages and includes elements like your brand name, logo, and a brief description. You can preview how your profile will appear to recipients as you input this information.

Expand image

You can send a test message directly from the Console to an RCS-compatible device by providing its phone number. This allows you to preview your RCS Sender's look and feel before it is officially launched.

You can continue to add test devices and send test messages after the RCS Sender has been submitted for approval.

Here you provide information about your business and messaging use case to ensure compliance with carrier and RCS requirements. It consists of four steps: Select countries, Sender review, User interaction, and Authorized representative.

Provide either access instructions on how to test your RCS Sender or screenshots or video demonstrating your RCS Sender's core messaging functionality and opt-out flow. You can capture this flow by using the test device that was set up during Sender creation.

The Sender review is required to meet RCS and carrier compliance requirements, and providing detailed instructions and media can help expedite the approval process.

Once you finalize your branded profile and compliance information, select Create in the Compliance section to submit your RCS Sender for approval. You cannot edit the information after submission and before approval, so ensure all details are accurate before selecting Create.

If you need to change your RCS Sender's profile after it's submitted, you must reach out to Twilio for assistance.

After you create your RCS Sender in the Twilio Console, you will receive an email in one to two days from the Google RCS Business Messaging Team with instructions on how to confirm your RCS brand use with Twilio. Follow the instructions in the email to confirm with Google so that Twilio can send RCS messages using your brand.

Depending on what countries you selected during the RCS Sender creation process, you may need to provide additional compliance information to satisfy specific country carrier requirements. If applicable, you can expect an email from Twilio within 5–10 days of creating your RCS Sender requesting additional compliance information. Follow the instructions in the email to provide the required information.

After the information submitted in Step 3 and Step 4 is reviewed, you will receive an email from Twilio confirming that your RCS Sender is approved and ready for configuration. You can also verify that the statuses of your RCS Sender's specific regions have moved from Under review to Active on the RCS Senders page in the Console.

Next, configure your RCS Sender in the Twilio Console by navigating to the RCS Senders page and selecting the RCS Sender. This opens the Sender Settings screen. Select Configuration and fill in the required details about the RCS Sender's Messaging Service and optional endpoint configuration.

You must configure your RCS Sender to use a new or existing Messaging Service. You can view your existing Services on the Messaging Services page in the Console.

Only one RCS Sender can be associated with a Messaging Service. The Service attempts to use the RCS Sender first for all messages it sends. If the recipient's device cannot receive RCS messages from this Sender, then Twilio will use a fallback SMS Sender.

For SMS fallback, Twilio will first select the short code, followed by the alphanumeric sender, followed by the long code. Alphanumeric senders aren't supported by MMS and won't be selected for MMS fallback. Learn more.

Select Save configuration to save your changes.

Now that you have a Messaging Service identified for your RCS Sender, you should configure and enable Advanced Opt-Out for that Service in order to meet compliance standards. Advanced Opt-Out allows you to customize the keywords and responses for opt-out, opt-in, and help messages for your RCS Sender.

You must provide a valid opt-out keyword in the local language of the regions where you are sending RCS messages, and send an opt-out confirmation message to the recipient.

To set up Advanced Opt-Out for a Messaging Service, navigate to the Messaging Services page in the Console. Select the Messaging Service associated with your RCS Sender and then select Opt-Out Management from the left-hand sidebar. Complete the configuration on this page, and select Enable Advanced Opt-Out. Once you enable these settings, Twilio applies these changes to all Senders in your Messaging Service's Sender Pool.

See Customizing Users' Opt-in and Opt-out Experience with Advanced Opt-Out for more information on the Advanced Opt-Out feature.

After completing the setup and configuration steps above, you can send RCS messages using the Programmable Messaging Create a Message resource. Programmable Messaging proactively checks if the recipient's device can support RCS and sends the message using SMS as a fallback if needed.

To send an RCS message, include your Messaging Service's SID in the API request using either the MessagingServiceSid or From parameter. See below for examples using each option.

You can set the MessagingServiceSid parameter in the API request to the Messaging Service SID assigned to your RCS Sender, shown as MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX in the code sample below. To find your Messaging Service's SID, check the Sid column on the Messaging Services page in the Console.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "My first RCS message. Hello, world!",
13
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
    to: "+155XXXXXXXX",
15
  });
16

17
  console.log(message.body);
18
}
19

20
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "My first RCS message. Hello, world!",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+14155552345",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+155XXXXXXXX",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

You can set the From parameter in the API request to the Messaging Service SID assigned to your RCS Sender, shown as MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX in the code sample below. To find your Messaging Service's SID, check the Sid column on the Messaging Services page in the Console.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "My first RCS message. Hello, world!",
13
    from: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
    to: "+155XXXXXXXX",
15
  });
16

17
  console.log(message.body);
18
}
19

20
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "My first RCS message. Hello, world!",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+155XXXXXXXX",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

You can send messages containing RCS-supported media formats using the MediaUrl field, and Twilio will automatically attempt delivery over RCS. Unsupported media formats may fallback to MMS. Devices that aren't RCS-capable will receive the message via MMS in supported regions, and Picture SMS elsewhere. The combination of text and media over RCS is supported for image and video files only.

RCS supports a maximum message size of 16 MB. However, when sending an RCS message that requires fallback to MMS, message sizes exceeding the MMS limit of 5 MB will be rejected.

To send an RCS message with media, you must include the MediaUrl parameter as well as your MessageServiceSid in the API request. RCS supports a single MediaUrl field per API request.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    from: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13
    mediaUrl: [
14
      "https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg",
15
    ],
16
    to: "+155XXXXXXXX",
17
  });
18

19
  console.log(message.body);
20
}
21

22
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "Hello! 👍",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+155XXXXXXXX",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

When users send messages to your RCS Sender, you can see those messages in your Programmable Messaging Logs page. You can also configure your Messaging Service to send a webhook when it receives an incoming message.

To stop using RCS, you can either send messages through a different Messaging Service or remove the RCS Sender from the Messaging Service.

To remove the RCS Sender from the Messaging Service, navigate to the Messaging Services page in the Console. Select the Messaging Service associated with your RCS Sender and then select Sender Pool from the left-hand sidebar. Use the Remove button to remove the RCS Sender from the Messaging Service.

After sending RCS messages, you can monitor and analyze your RCS traffic using different tools such as Programmable Messaging Logs and Messaging Insights.

You can also perform A/B testing between RCS and other channels to compare their effectiveness.

The primary indicator that a message was sent with RCS is the From field containing rcs:<SenderId>. This field is visible in Programmable Messaging Logs, outbound message status callbacks, and Fetch a Message resource request results.

Check the Programmable Messaging Logs page in the Console for a detailed record of each RCS message request. To filter and view logs for RCS messages only, set the From field to rcs:.

RCS messages can have the following statuses:

• Accepted
• Queued
• Sent
• Delivered
• Undelivered
• Read

If you don't see a log for your message, the message likely encountered an error in your application or potentially with Twilio's API. You can view errors on the Error Logs page in the Console.

RCS messages are automatically included in Messaging Insights analytics. Messaging Insights allow you to quickly assess your application's messaging activities, identify and debug issues, optimize delivery, monitor fraud protection, and find areas to boost engagement.

Messaging Insights real-time dashboards display delivery metrics, engagement metrics, and more for your messages. You can find the dashboards in the Twilio Console under Monitor > Insights > Messaging. To view RCS metrics only, filter the dashboards so that the Channel field equals RCS.

Expand image

In many regions, RCS tracks "delivered" and "read" statuses more reliably than SMS does. For this reason, we recommend using other metrics such as clicks or conversions when A/B testing the two channels.