> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RCS

> Register an RCS agent, link it to your agent, and send rich cards, carousels, and suggested replies to Android users

After this guide, end users on RCS-capable phones message a branded sender and get replies from your [agent](/concepts/agents) with cards, carousels, media, and tap-to-reply suggestions instead of plain text. RCS is delivered through Vonage RCS Business Messaging (RBM): you need an RBM agent (a sender id, display name, logo, and banner) that has been created and approved with the carrier program . Setup is over the REST API; there is no CLI command.

*Verified against lua-cli 3.33.0.*

**Before you begin**

* An RBM agent's `senderId` and `displayName`, plus its logo and banner URLs.
* An API key with the `telephony:write` scope on your organization (`telephony:read` to list, `telephony:manage` to remove or unlink).
* The id of the Lua agent that should answer.

<Steps>
  <Step title="Register the RCS agent">
    Create the record with `POST /developer/orgs/<orgId>/rcs-agents` and a body of `senderId`, `displayName`, and optionally `description`, `logoUrl`, `bannerUrl`, and `geoAvailability` (a list of strings). A missing `senderId` or `displayName` fails with `senderId and displayName are required`; a sender id that already exists is refused.

    The record starts in status `pending`; `testing`, `live`, and `suspended` are the other values, and capability checks and bulk checks need `testing` or `live` . `GET /developer/orgs/<orgId>/rcs-agents` lists records with a `status` filter; `DELETE …/rcs-agents/<id>` suspends the record and leaves the RBM agent untouched.
  </Step>

  <Step title="Link it to your agent">
    Connect the sender to the agent that answers with `POST /developer/orgs/<orgId>/rcs-agents/<id>/link` and a body of `{ "luaAgentId": "<agentId>" }`. The response shows `linkedAgentId`. `DELETE …/link` disconnects it. Inbound routing also needs an RCS channel record for the sender id on the agent, which this call doesn't create.&#x20;
  </Step>

  <Step title="Check that a number can receive RCS">
    Before you message a number, ask whether its device supports RCS. `POST …/rcs-agents/<id>/capability-check` with `{ "phoneNumber": "+15551234567" }` returns `isReachable` and the `features` the device supports; it works once the record is `testing` or `live`. For a list, `POST …/bulk-capability-check` with 500 to 10,000 `phoneNumbers` returns `reachableUsers` and an `estimatedReachabilityPercent`; it works only for a `live` record.
  </Step>

  <Step title="Verify">
    Send a message to the sender from an RCS-capable phone. The reply arrives as RCS; a reply that uses list items shows as cards, and `Lua.request.channel` inside your tools is `rcs`. Confirm the turn with `lua logs --type agent_response`.
  </Step>
</Steps>

## Channel behavior

| Capability                       | Supported                                                                                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inbound text, tapped suggestions | Yes; a tapped reply or button arrives as its postback value or label                                                                                 |
| Inbound media and location       | Yes, as a placeholder in the text (`[Image: <url>]`, `[Location: <lat>, <long>]`)                                                                    |
| List items                       | Rich cards: title, body, image; a horizontal list becomes a carousel                                                                                 |
| Images, documents, video         | Image, file, and video messages; `.mp4`, `.m4v`, `.mpeg`, `.webm`, and `.h263` URLs are sent as video                                                |
| Actions and links                | Suggestions on the last text message: reply chips, dial chips when the action names a phone number, open-URL chips labelled with the link's hostname |
| Reactions                        | Text fallback                                                                                                                                        |
| Payment links                    | Not rendered                                                                                                                                         |
| Proactive sends                  | Not in `Channels.send`, and `user.send()` can't reach it                                                                                             |

The platform doesn't fall back to SMS when a number can't receive RCS; check capability first and use [SMS](/channels/sms-and-phone-numbers) for the rest.  The [formatting overview](/channels/formatting/overview) has the component matrix for every channel.

## Limits

| Limit                   | Value                                                                             |
| ----------------------- | --------------------------------------------------------------------------------- |
| Text message            | 3,072 characters; longer replies are split at paragraph, line, or sentence breaks |
| Card title              | 200 characters                                                                    |
| Card text               | 2,000 characters                                                                  |
| Suggestions per message | 11; 4 per card; 25 characters each                                                |
| Carousel cards          | 10                                                                                |
| Bulk capability check   | 500 to 10,000 numbers                                                             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="RCS agent not found or not in testing/live status">
    Capability checks need a `testing` or `live` record. Check `status` with `GET …/rcs-agents/<id>`; a `pending` record can be edited but not used for checks.
  </Accordion>

  <Accordion title="Bulk capability check requires between 500 and 10,000 phone numbers">
    The bulk check needs at least 500 distinct numbers and at most 10,000; a repeated number fails with `Bulk capability check does not allow duplicate phone numbers`. For fewer, call the single capability check per number.
  </Accordion>

  <Accordion title="Messages to the sender get no reply">
    Inbound messages are routed by the sender id they were sent to, through the agent's RCS channel record, which the link call doesn't create. Confirm that record exists and its sender id matches the RBM agent exactly; then check `lua logs --type user_message` for the inbound turn.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Response formatting" href="/channels/formatting/overview">List items, actions, and links that become cards and chips.</Card>
  <Card title="SMS and phone numbers" href="/channels/sms-and-phone-numbers">Reach the numbers that can't receive RCS.</Card>
  <Card title="About channels" href="/concepts/channels">How channels reach your code.</Card>
  <Card title="RCS agents API" href="/reference/rest/rcs-agents">Every field and status.</Card>
</Columns>