Send and receive RCS messages

On this page, you'll learn how to send RCS messages. All RCS messages are branded and originate from a verified sender by default.

For information about RCS features, see RCS Business Messaging.

Complete the prerequisites

Before you send an RCS message, complete the RCS setup.

Send an RCS message with automatic fallback to SMS or MMS

You can send RCS messages using code that makes HTTP POST requests to the Message resource in the Twilio REST API.

When an RCS sender is in a Messaging Service's Sender Pool, Programmable Messaging defaults to RCS as the first-attempt channel. Programmable Messaging proactively checks whether the recipient's device supports RCS. Messages that can't be delivered over RCS automatically fall back to SMS or MMS, using other senders in the Messaging Service's Sender Pool.

To send an RCS message, follow the steps to send an SMS message. Set the MessagingServiceSid or From field to the Messaging Service SID assigned to the RCS Sender. To find a Messaging Service's SID, check the Sid column on the Messaging Services page in the Twilio Console.

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    body: "My first RCS message. Hello, world.",
13    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14    to: "+155XXXXXXXX",
15  });
16
17  console.log(message.body);
18}
19
20createMessage();

Specify a fallback SMS or MMS sender

You can specify which SMS or MMS sender to use during fallback in two ways:

Add a single SMS or MMS capable sender to the Messaging Service's sender pool. That sender is used for fallback automatically.
Specify the fallback sender using the FallbackFrom parameter. You can specify any phone number in the same Account SID as the Messaging Service, even if it's not in the sender pool. The FallbackFrom parameter only works when sending through a Messaging Service.

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    body: "An example message while specifying a fallback sender.",
13    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14    to: "+18005550100",
15  });
16
17  console.log(message.body);
18}
19
20createMessage();

Send an RCS message without automatic fallback to SMS or MMS

You can also send RCS messages without relying on Twilio's automatic fallback. You must implement your own fallback orchestration logic to retry failed RCS attempts on another channel.

Use a Messaging Service

To turn off fallback when you send an RCS message through a Messaging Service, add the rcs: prefix to the recipient phone number in the To field.

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    body: "My first RCS message. Hello, world.",
13    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14    to: "rcs:+155XXXXXXXX",
15  });
16
17  console.log(message.body);
18}
19
20createMessage();

Without a Messaging Service

To turn off fallback when you send an RCS message without using a Messaging Service, set the RCS Sender ID in the From field and the recipient phone number in the To field.

The RCS Sender ID appears on the Settings page for the RCS Sender in the Twilio Console.

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    body: "My first RCS message. Hello, world.",
13    from: "rcs:brand_xyz123_agent",
14    to: "rcs:+155XXXXXXXX",
15  });
16
17  console.log(message.body);
18}
19
20createMessage();

For information on RCS error codes and using RCS without Twilio's automatic fallback, see RCS Messaging Best Practices and FAQ.

Send an RCS message that contains media

To send messages containing RCS-supported media formats and sizes, include the media URL in the RCS API call as shown in the following example. Twilio fetches the media from the URL you provide.

The media URL must be publicly accessible. Twilio can't fetch media from hidden URLs or URLs that require authentication.

Twilio automatically attempts delivery over RCS. Unsupported media formats may fall back to MMS. Devices that aren't RCS-capable receive the message as MMS in MMS-supported regions, or as Picture SMS elsewhere.

Twilio supports combining text and media in a single request for image and video files. Twilio automatically packages the text and media as an RCS Rich Card for delivery, so you aren't billed for two separate messages. When you use a Rich Card, Twilio processes and bills text and media in a single RCS request.

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    mediaUrl: [
13      "https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg",
14    ],
15    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
16    to: "+155XXXXXXXX",
17  });
18
19  console.log(message.body);
20}
21
22createMessage();

Send an RCS message that contains rich content

(new)

Beta

If you're interested in sending rich content on RCS without using a Content Template, you can request access to the private beta of the Communications API.

You can create rich content using Content Templates and send that content through RCS. RCS supports the following rich content types:

	Rich content support
RCS Feature	Content Type
Rich Card	`twilio/card`
Chip List	`twilio/card`
Basic Text	`twilio/text`
Media	`twilio/media`
Rich Card Carousel	`twilio/carousel`
Webviews	`twilio/card`

For devices that aren't RCS-capable, you can define customized fallback to SMS and MMS in applicable regions by defining multiple types in a Content Template.

To send rich content through RCS:

Define your rich content in the API or the Twilio Console.
In the API response or in the Twilio Console, copy the unique Content SID starting with HX that identifies your rich content.
Add the ContentSid and content variables to the Send an RCS message with automatic fallback to SMS or MMS code sample as shown in the following example.

To learn more about content variables, see Using Variables.

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    contentSid: "HXXXXXXXXXXXXX",
13    contentVariables: JSON.stringify({ 1: "Name" }),
14    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
15    to: "+1555XXXXXXX",
16  });
17
18  console.log(message.body);
19}
20
21createMessage();

Receive an RCS message

When users send messages to an RCS Sender, messages are shown on the Programmable Messaging Logs page in the Twilio Console. You can also configure a Messaging Service to send a webhook when it receives an incoming message.

Let customers initiate a chat with an RCS Sender

Your customers can start a chat with an RCS Sender from a deep link URL. You can embed the URL as a button, link, or QR code in an email, app, or website. If users can't send or receive RCS messages, the fallback phone number handles the message.

Deep link URL Format

sms:+1555XXXXXXX?service_id=brand_xyz123_agent%40rbm.goog&body=Hello%20World

Parameter	Description	Necessity
`+1555XXXXXXX`	Fallback number	Required
`brand_xyz123_agent`	RCS Sender ID, excluding `rcs:`	Required
`Hello%20World`	URL-encoded pre-filled message	Optional

The RCS Sender ID appears on the Settings page for the RCS Sender.

You can also use the Google SMS link creator to generate the deep link and QR code.

Monitor and analyze traffic for RCS messages that you send

After you send RCS messages, you can monitor and analyze your RCS traffic by using Programmable Messaging Logs in the Twilio Console and Messaging Insights. If you don't see a log for your message, you can view errors on the Error Logs page in the Twilio Console.

If Twilio successfully delivers the message over RCS, the From field contains rcs:<SenderId>. You can view this field in the Programmable Messaging Logs in the Twilio Console, outbound message status callbacks, and Fetch a Message resource request results.

In many regions, RCS tracks delivered and read statuses more reliably than SMS does. If you need to A/B test the two channels, consider using other metrics, such as clicks or conversions.