Send and receive RCS messages

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

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
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();

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

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
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: "rcs:+155XXXXXXXX",
15
  });
16

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

20
createMessage();

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.

You can find the RCS Sender ID at the top of the RCS Sender's Settings page in the Twilio 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: "rcs:brand_xyz123_agent",
14
    to: "rcs:+155XXXXXXXX",
15
  });
16

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

20
createMessage();

See RCS Messaging Best Practices and FAQ for information on RCS error codes and using RCS without Twilio's fallback.

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 will fetch the media from the URL provided.

The media URL must be publicly accessible. Twilio cannot 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 by MMS in MMS-supported regions, and Picture SMS elsewhere.

Twilio supports combining text and media in a single request for image and video files. The text and media RCS message is automatically packaged as an RCS Rich Card by Twilio for delivery, ensuring you are not 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
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
    mediaUrl: [
13
      "https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg",
14
    ],
15
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
16
    to: "+155XXXXXXXX",
17
  });
18

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

22
createMessage();

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

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:

1. Define your rich content in the API or the Twilio Console.

2. In the API response or in the Twilio Console, find the unique Content SID starting with HX that identifies your rich content.

3. Add the ContentSid and content variables to the Send an RCS message with automatic fallback to SMS or MMS code 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
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
    contentSid: "HXXXXXXXXXXXXX",
13
    contentVariables: JSON.stringify({ 1: "Name" }),
14
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
15
    to: "+1555XXXXXXX",
16
  });
17

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

21
createMessage();

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.

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 based on your requirements. A fallback phone number is used if users cannot send or receive RCS messages.

Deep link URL Format

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

The RCS Sender ID can be found at the top the RCS Sender's Settings page.

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

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 sent the message with 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. If you need to A/B test the two channels, consider using other metrics, such as clicks or conversions.