Skip to contentSkip to navigationSkip to topbar
On this page

Send and receive branded RCS messages


On this page, you'll learn how to use Twilio Programmable Messaging(link takes you to an external page) to programmatically send RCS messages with brand details using your web application or cURL(link takes you to an external page).

For information about RCS features, see RCS Business Messaging.


Complete the prerequisites

complete-the-prerequisites page anchor

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(link takes you to an external page).

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

Send an RCS message that contains media

send-an-rcs-message-that-contains-media page anchor

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(link takes you to an external page), and Picture SMS(link takes you to an external page) 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 separately for the text and media. 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();

Send an RCS message that contains rich content

send-an-rcs-message-that-contains-rich-content page anchor

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 FeatureContent Type
Rich Cardtwilio/card
Chip Listtwilio/card
Basic Texttwilio/text
Mediatwilio/media
Rich Card Carouseltwilio/carousel

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 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(link takes you to an external page). 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

let-customers-initiate-a-chat-with-an-rcs-sender page anchor

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
ParameterDescriptionNecessity
+1555XXXXXXXFallback numberRequired
brand_xyz123_agentRCS Sender ID, excluding rcs:Required
Hello%20WorldURL-encoded pre-filled messageOptional

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(link takes you to an external page) to generate the deep link and QR code.


Monitor and analyze traffic for RCS messages that you send

monitor-and-analyze-traffic-for-rcs-messages-that-you-send page anchor

After you send RCS messages, you can monitor and analyze your RCS traffic by using Programmable Messaging Logs in the Twilio Console(link takes you to an external page) 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(link takes you to an external page).

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(link takes you to an external page), 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.