Send and receive branded RCS messages
On this page, you'll learn how to use Twilio Programmable Messaging to programmatically send RCS messages with brand details using your web application or cURL.
For information about RCS features, see RCS Business Messaging.
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12body: "My first RCS message. Hello, world.",13messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14to: "+155XXXXXXXX",15});1617console.log(message.body);18}1920createMessage();
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 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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12mediaUrl: [13"https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg",14],15messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",16to: "+155XXXXXXXX",17});1819console.log(message.body);20}2122createMessage();
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 |
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, find the unique Content SID starting with
HX
that identifies your rich content. -
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12contentSid: "HXXXXXXXXXXXXX",13contentVariables: JSON.stringify({ 1: "Name" }),14messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15to: "+1555XXXXXXX",16});1718console.log(message.body);19}2021createMessage();
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
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 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.