openai/twilio-rcs-messaging

Overview

RCS (Rich Communication Services) Business Messaging delivers branded, rich messages natively in the phone's default messaging app — no separate app needed. Messages show your brand logo, colors, and verified sender name. Supports rich cards, carousels, suggested actions, and media.

RCS uses the same messages.create() API as SMS and WhatsApp. For the full channel comparison and onboarding sequence, see twilio-messaging-overview.

Device Support

| Platform | Support | Notes | |----------|---------|-------| | Android | Most devices via Google Messages | Carrier must also support RCS in the region | | iOS | iOS 18+ | P2P RCS is not the same as RCS Business Messaging. A device that sends RCS to other people may not receive RCS Business Messages — this depends on both Apple and the carrier. Check via RcsCapabilityFetcher before sending. |

Regional Availability

RCS availability depends on carrier approval per country. See RCS regional availability for the current list. US carriers (T-Mobile, AT&T, Verizon) are supported. Global support is expanding.

---

Prerequisites

• Twilio paid account — free trials cannot use RCS
• Messaging Service (RCS senders must be added to a Messaging Service)
• Environment variables: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN — See twilio-iam-auth-setup for credential setup
• SDK: pip install twilio / npm install twilio

---

Compliance Onboarding (US)

RCS onboarding takes 4-6 weeks minimum. A Twilio onboarding specialist reviews everything before carrier submission. You won't be charged until you go live.

Part 1: Sender Profile Setup

Create your RCS Sender in Console with:

| Asset | Requirements | |-------|-------------| | Display name | Must be unique — carriers reject identical names + logos | | Logo | 224x224px, max 50KB, PNG/JPEG | | Banner | 1140x448px, max 200KB | | Accent color | Hex code, must have 4.5:1 contrast ratio vs white | | Description | What your business does and why you're messaging | | Phone number | Customer support contact number | | Website | Must match business identity |

Part 2: Privacy Policy & Terms of Service

• Privacy policy URL — must be publicly accessible
• Terms of Service URL — must be publicly accessible
• Both must cover SMS/RCS messaging, data handling, opt-out process
• The privacy policy must state that information will be shared with third parties for the purpose of transmitting RCS messages
• Some countries require local-language versions

For US-specific compliance details, see the RCS Compliance Onboarding Guide.

Part 3: Eligibility & Acceptable Use

US carriers require:

• Legal business name matching EIN records
• EIN (Employer Identification Number)
• Business must not be on restricted industries list (cannabis, firearms, etc.)
• CTIA Messaging Principles and Best Practices handbook compliance

Part 4: Campaign Details

• Use case category (transactional, promotional, OTP, mixed)
• Traffic volume estimates
• Campaign description with specific messaging scenarios
• For recurring messages: frequency, content types

Part 5: Opt-In & Consent

• Describe how users opt in to receive RCS messages
• Must show explicit consent collection mechanism
• Opt-in must be specific to RCS/messaging (not buried in general ToS)
• HELP and STOP keyword handling required

Part 6: Sample Messages

• 2+ sample messages that match your declared use case
• Must include opt-out language
• Must reflect actual message content (not generic)

Part 7: Common Rejection Reasons

| Rejection reason | Fix | |-----------------|-----| | Display name not unique | Choose a distinct name — carriers reject duplicates | | Logo/banner don't meet specs | Check dimensions and file size exactly | | Privacy policy doesn't mention messaging | Add RCS/SMS data handling section | | Sample messages don't match use case | Align samples with campaign description | | Opt-in process too vague | Show specific UI/flow for consent collection | | Business info doesn't match EIN | Legal name and EIN must match IRS records exactly | | Media URLs not publicly accessible | All images/videos must be on public URLs — carriers verify during review |

Registration Flow

1. Create RCS Sender in Console → complete all 7 parts above
2. Test Phase — Add test devices, send and receive messages without carrier approval. Non-test devices get SMS fallback.
3. Compliance Submission — Twilio specialist reviews, then submits to Google + carriers:
   • Google registration: authorized rep details, opt-in/opt-out policy, use case video, interaction flow
   • US registration (additional): legal business name + EIN, traffic metrics, CTIA compliance, HELP/STOP examples
4. Carrier approval — Per-carrier, per-country. First carrier approval = you can go live in that country.
5. Go live — Add RCS Sender to your Messaging Service. Start sending.

---

Sending RCS Messages

RCS uses the same messages.create() API. No address prefix needed — Twilio routes based on the sender type.

Python

import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

message = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Your order has shipped! Track it here: https://example.com/track/12345"
)
print(message.sid, message.status)

Node.js

const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const message = await client.messages.create({
    messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to: "+15558675310",
    body: "Your order has shipped! Track it here: https://example.com/track/12345",
});
console.log(message.sid, message.status);

Rich Cards & Carousels

Use Content Templates for rich RCS messages (cards with images, titles, descriptions, and action buttons). Create templates via twilio-content-template-builder, then send with contentSid:

Python

message = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    content_sid="HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    content_variables='{"1": "Order #12345", "2": "$49.99"}'
)

SMS Fallback

When a recipient's device doesn't support RCS Business Messaging, Twilio automatically falls back to SMS — no code changes needed. This is handled at the Messaging Service level.

• Fallback is automatic when the Messaging Service has both RCS sender and phone numbers
• If you send via messagingServiceSid, Twilio checks RCS capability first, then falls back to SMS
• Without Twilio's fallback: the message simply fails to deliver (no automatic retry to SMS)

---

Multiple RCS Senders

A single brand can have multiple RCS senders, but each must have a distinct use case (e.g., one for transactional, one for marketing). The use case must be clearly different — carriers reject duplicate-purpose senders for the same brand.

• Each sender has its own display name, logo, and campaign details
• All senders go through independent carrier approval
• Each sender can only belong to one Messaging Service

ISV Path

ISVs (Independent Software Vendors) registering RCS senders for client businesses:

• Can register on behalf of clients using the same compliance process
• Each client business needs its own RCS Sender with its own branding
• The ISV's Twilio account can host multiple RCS Senders
• Programmatic sender creation at scale is not supported — each sender must be created individually in Console

---

Common Errors

| Error | Meaning | Fix | |-------|---------|-----| | Sender not approved | RCS sender hasn't completed carrier approval | Complete compliance onboarding; use test devices in the meantime | | Device not capable | Recipient can't receive RCS Business Messages | Twilio falls back to SMS automatically if fallback is configured | | Media URL inaccessible | Rich card image/video not publicly accessible | Host media on public URLs | | Display name rejected | Name conflicts with existing RCS sender | Choose a unique display name |

---

CANNOT

• Cannot use RCS on free trial accounts — Paid account required
• Cannot send RCS without a Messaging Service — RCS senders must be added to a Messaging Service
• Cannot add an RCS sender to multiple Messaging Services — Each sender belongs to one service only
• Cannot create RCS senders programmatically at scale — Console-only, one at a time
• Cannot skip carrier approval — Even with Google approval, each carrier must independently approve in each country
• Cannot guarantee RCS delivery to iOS — iOS 18 supports P2P RCS, but RCS Business Messaging support depends on Apple + carrier. Always have SMS fallback.
• Cannot control fallback behavior per-message — Fallback to SMS is automatic at the Messaging Service level when both RCS and SMS senders are present
• Cannot send RCS to landlines — Mobile-only channel
• Cannot use unique display names that match existing senders — Carriers enforce uniqueness globally
• Cannot update sender profile after approval without re-review — Profile changes trigger a new carrier review cycle

---

Next Steps

• Channel overview and onboarding guide: twilio-messaging-overview
• Create rich message templates: twilio-content-template-builder
• Set up Messaging Service for sender pool + fallback: twilio-messaging-services
• Compliance registration for other channels: twilio-compliance-onboarding
• Number and sender type selection: twilio-numbers-senders