Skip to main content
After this guide, end users on RCS-capable phones message a branded sender and get replies from your agent 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.
1

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.
2

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.
3

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.
4

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.

​
Channel behavior

The platform doesn’t fall back to SMS when a number can’t receive RCS; check capability first and use SMS for the rest. The formatting overview has the component matrix for every channel.

​
Limits

​
Troubleshooting

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.
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.
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.

​
Next steps

Response formatting

List items, actions, and links that become cards and chips.

SMS and phone numbers

Reach the numbers that can’t receive RCS.

About channels

How channels reach your code.

RCS agents API

Every field and status.