> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://agentphone.to/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentphone.to/docs/_mcp/server.

# RCS Business Messaging

> Branded rich messaging to RCS-capable handsets, with automatic SMS fallback

RCS Business Messaging lets your agent text as a **branded sender** — your name and logo on the thread instead of a bare phone number — with delivery and read receipts, and tappable quick-reply chips. It runs through the same `POST /v1/messages` endpoint as every other channel.

> **Note**
>
> **RCS is concierge-onboarded.** Carriers approve each brand individually, so there is no self-serve signup yet. Reach out to [founders@agentphone.to](mailto:founders@agentphone.to) and we set up your RCS agent, run the carrier launch process with you, and place the line on your account.

## Your RCS line

An RCS agent arrives on your account as a line whose address starts with `rcs_` (for example `rcs_acme`) instead of a phone number. It behaves like any other number: attach it to an agent, see its threads in Conversations, receive inbound through the same webhooks.

## Sending

RCS fields and the `rcs` channel override are intentionally omitted from the public OpenAPI schema and generated SDK types while onboarding is concierge-only. The HTTP request below is supported for enabled accounts; use it instead of expecting these fields in the generated SDK.

Address RCS **explicitly** — use your `rcs_` address as `from_number`, or pass `channel: "rcs"`:

```bash
curl -X POST https://api.agentphone.ai/v1/messages \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "rcs_acme",
    "to_number": "+13105550123",
    "channel": "rcs",
    "body": "Your order has shipped! Want delivery updates?",
    "buttons": ["Yes, keep me posted", "No thanks"]
  }'
```

To select your branded RCS line reliably, specify it explicitly. Automatic selection by `agent_id` depends on eligible attached numbers and their capabilities; it is not a promise to use SMS or your branded RCS identity.

`buttons` become tappable quick-reply chips (up to 11 per message, 25 characters each). A tap comes back as a normal inbound message carrying the chip's text.

## Rich cards

For an image with text, send a `card` with an empty `body`. Do not also pass `media_urls`, a `carousel`, or top-level `buttons`. The card accepts a title (up to 200 characters), description (up to 2,000), and a public HTTPS `media_url`; at least one of those content fields must be present.

```bash
curl --fail-with-body "https://api.agentphone.ai/v1/messages" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "rcs_acme",
    "to_number": "+14155550123",
    "channel": "rcs",
    "body": "",
    "card": {
      "title": "Your order is ready",
      "description": "Collect it at the front desk.",
      "media_url": "https://example.com/order.jpg",
      "media_height": "MEDIUM",
      "orientation": "VERTICAL"
    },
    "fallback_text": "Your order is ready. Collect it at the front desk."
  }'
```

Replace the sample image URL with your own reachable asset. `media_height` can be `SHORT`, `MEDIUM`, or `TALL` and requires `media_url`; `orientation` can be `VERTICAL` or `HORIZONTAL`. The example's `fallback_text` requires an SMS fallback line configured during onboarding.

## SMS fallback

Not every handset can receive RCS. If your line has an SMS fallback number configured (we set this up with you during onboarding), a send to a non-RCS handset is delivered automatically as a plain text from that number — same API call, nothing to detect on your side.

The message's `channel` always reflects what you asked for (`rcs`); when delivery actually happened over SMS, the message carries `deliveredChannel: "sms"` so downgrades are never invisible. In the dashboard those messages show "Delivered as SMS".

The fallback number is a real number on your account: replies to it reach the same agent, and it can't be released while it's serving as a fallback.

## Opt-outs — what you must send yourself

When a recipient replies STOP (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT), AgentPhone records the opt-out and **blocks further sends** to them from your RCS agent — subsequent sends return a clear `403`. A reply of START opts them back in.

AgentPhone never sends messages on your behalf, so **your agent or backend must send the opt-out confirmation text itself** (the STOP response you provided during carrier onboarding). The same applies to HELP responses. One confirmation message is allowed after a STOP; anything further is blocked until the recipient opts back in.

## Billing

RCS text is billed per 160-byte UTF-8 segment; rich media is billed per message, inbound and outbound. Standard rates are \$0.013/text segment and \$0.031/rich-media message, with account-specific overrides possible. Check Billing (the **RCS** tab in transaction history). A message that falls back to SMS bills at the rate of the send you requested.