twilio-rcs-messaging

What this skill does

## 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](https://www.twilio.com/docs/rcs/regional) 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](https://help.twilio.com/articles/49174994355355-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**
```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**
```javascript
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**
```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 h