RCS agents

An RCS agent is the carrier-side sender identity (sender ID, display name, branding) an organization uses for RCS Business Messaging. These routes register that identity, record which agent answers its messages, and check whether a phone number can receive RCS. For the channel setup, see RCS. Verified against lua-cli 3.33.0.

Base URL and authentication

Every route sits under https://api.heylua.ai/developer/orgs/:orgId/rcs-agents and takes Authorization: Bearer <<YOUR_API_KEY>>; the REST API overview covers keys, scopes, and the error envelope. Every route checks a telephony scope on the organization in the path: telephony:read lists and inspects, telephony:write creates, updates, links, and runs capability checks, and telephony:manage suspends and unlinks. There is no CLI equivalent for this family. A POST answers 201. The :agentId path segment on these routes is the RCS agent’s ID (the id field below), not the Lua agent ID. The Lua agent is passed as luaAgentId in the link body.

RCS agent object

string

RCS agent ID; use it in the path of the other routes.

string

Owning organization.

string

Carrier RBM sender ID. Unique across organizations.

string

Name shown to recipients.

string

Optional description.

string

Logo image URL.

string

Banner image URL.

string

One of pending, testing, live, suspended. Set with PATCH; the platform never advances it.

string

Inbound webhook URL stored on the record. This API does not register it with the carrier.

string[]

Reserved; always [].

string[]

Regions where the agent is available, as free-form strings.

string

User ID of the creator.

string

Creator email, when known.

string

The Lua agent recorded for this sender, once linked.

number

Unix time in milliseconds.

Endpoints

POST /developer/orgs/:orgId/rcs-agents

Registers an RCS agent from carrier RBM agent details; the record starts in status pending. Scope telephony:write. Answers 201 with the RCS agent object.

string

required

The RBM sender ID issued by the carrier.

string

required

Name shown to recipients.

string

Description.

string

Logo image URL.

string

Banner image URL.

string[]

Regions where the agent is available.

GET /developer/orgs/:orgId/rcs-agents

Lists the organization’s RCS agents. Scope telephony:read.

string

One of pending, testing, live, suspended.

number

default:50

Maximum results.

number

Results to skip.

Response 200 with { agents: RcsAgent[], count }, where count is the total matching the filter.

GET /developer/orgs/:orgId/rcs-agents/:agentId

Returns one RCS agent object. Scope telephony:read. 404 when unknown.

PATCH /developer/orgs/:orgId/rcs-agents/:agentId

Updates an RCS agent that is not suspended. Scope telephony:write. Answers 200 with the updated object; 404 when the agent is unknown or suspended.

string

Name shown to recipients.

string

Description.

string

Logo image URL.

string

Banner image URL.

string

One of pending, testing, live, suspended. Written as given; neither the value nor the transition is validated. This is the only way an RCS agent moves from pending to testing or live, so set it once the carrier has approved the agent.

string

Inbound webhook URL to store.

string[]

Regions where the agent is available.

DELETE /developer/orgs/:orgId/rcs-agents/:agentId

Suspends the RCS agent record. Scope telephony:manage. The carrier-side RBM agent is not deleted. Suspended agents are excluded from PATCH, link, and the capability checks, and cannot be restored through this API. Response 200 with { "success": true }.

POST /developer/orgs/:orgId/rcs-agents/:agentId/link

Records the Lua agent for this sender. Scope telephony:write. Answers 201 with the updated object and linkedAgentId set. Inbound messages are routed by an RCS channel record for the sender ID, which this route does not create; set up the channel as described in RCS.

string

required

The Lua agent ID.

DELETE /developer/orgs/:orgId/rcs-agents/:agentId/link

Removes the recorded Lua agent. Scope telephony:manage. Answers 200 with the updated object.

POST /developer/orgs/:orgId/rcs-agents/:agentId/capability-check

Checks whether one phone number can receive RCS from this agent. Scope telephony:write. The RCS agent must be testing or live.

string

required

The number to check, in E.164.

Response 201 with { phoneNumber, isReachable, features? }: the number checked, whether the device supports RCS, and the RCS features the device reported when reachable.

POST /developer/orgs/:orgId/rcs-agents/:agentId/bulk-capability-check

Estimates RCS reachability across a list of numbers. Scope telephony:write. The RCS agent must be live, which is checked first; the list must then hold between 500 and 10,000 numbers with no duplicates.

string[]

required

Numbers in E.164.

Response 201 with { reachableUsers, totalRandomSampleUserCount, reachableRandomSampleUserCount, estimatedReachabilityPercent }: the numbers found reachable, the size of the sample the carrier checked, the reachable numbers within it, and their ratio as a percentage rounded to two decimals (0 when the sample is empty).

Errors

Status	Message	Meaning
`400`	`senderId and displayName are required`	Create body missing a required field; pass both
`400`	`An RCS agent with this sender ID already exists`	The sender ID is registered; list by organization to find it
`400`	`An RCS agent with this sender ID was previously deleted. Contact support to restore it.`	The sender ID belongs to a suspended record
`400`	`luaAgentId is required`	Link body missing `luaAgentId`
`400`	`phoneNumber is required`, `phoneNumbers array is required`	Capability-check body malformed
`400`	`Bulk capability check requires between 500 and 10,000 phone numbers`, `Bulk capability check does not allow duplicate phone numbers`	Bulk list out of range or with repeats; fix the list
`400`	A carrier message	The carrier rejected the bulk check
`403`	—	The key lacks the `telephony` scope on this organization
`404`	`RCS agent not found`	Unknown ID; list by organization
`404`	`RCS agent not found or suspended`	Update or link on a suspended agent; create a new RCS agent
`404`	`RCS agent not found or not in testing/live status`	Capability check on a `pending` agent; set `status` with `PATCH` once the carrier has approved it
`404`	`RCS agent not found or not in live status`	Bulk check on an agent that is not `live`; use the single check until it is

Example

Check whether a customer’s phone can receive RCS before choosing a channel.

const response = await fetch(
  'https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/rcs-agents/<<RCS_AGENT_ID>>/capability-check',
  {
    method: 'POST',
    headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
    body: JSON.stringify({ phoneNumber: '+15551234567' }),
  },
);
if (!response.ok) throw new Error(`Capability check failed: ${response.status} ${await response.text()}`);
const check: { phoneNumber: string; isReachable: boolean; features?: string[] } = await response.json();
console.log(check.isReachable, check.features ?? []);

curl -X POST "https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/rcs-agents/<<RCS_AGENT_ID>>/capability-check" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+15551234567" }'

SDK

CLI

REST API

Base URL and authentication

RCS agent object

Endpoints

POST /developer/orgs/:orgId/rcs-agents

GET /developer/orgs/:orgId/rcs-agents

GET /developer/orgs/:orgId/rcs-agents/:agentId

PATCH /developer/orgs/:orgId/rcs-agents/:agentId

DELETE /developer/orgs/:orgId/rcs-agents/:agentId

POST /developer/orgs/:orgId/rcs-agents/:agentId/link

DELETE /developer/orgs/:orgId/rcs-agents/:agentId/link

POST /developer/orgs/:orgId/rcs-agents/:agentId/capability-check

POST /developer/orgs/:orgId/rcs-agents/:agentId/bulk-capability-check

Errors

Example

See also

​Base URL and authentication

​RCS agent object

​Endpoints

​POST /developer/orgs/:orgId/rcs-agents

​GET /developer/orgs/:orgId/rcs-agents

​GET /developer/orgs/:orgId/rcs-agents/:agentId

​PATCH /developer/orgs/:orgId/rcs-agents/:agentId

​DELETE /developer/orgs/:orgId/rcs-agents/:agentId

​POST /developer/orgs/:orgId/rcs-agents/:agentId/link

​DELETE /developer/orgs/:orgId/rcs-agents/:agentId/link

​POST /developer/orgs/:orgId/rcs-agents/:agentId/capability-check

​POST /developer/orgs/:orgId/rcs-agents/:agentId/bulk-capability-check

​Errors

​Example

​See also

Base URL and authentication

RCS agent object

Endpoints

POST /developer/orgs/:orgId/rcs-agents

GET /developer/orgs/:orgId/rcs-agents

GET /developer/orgs/:orgId/rcs-agents/:agentId

PATCH /developer/orgs/:orgId/rcs-agents/:agentId

DELETE /developer/orgs/:orgId/rcs-agents/:agentId

POST /developer/orgs/:orgId/rcs-agents/:agentId/link

DELETE /developer/orgs/:orgId/rcs-agents/:agentId/link

POST /developer/orgs/:orgId/rcs-agents/:agentId/capability-check

POST /developer/orgs/:orgId/rcs-agents/:agentId/bulk-capability-check

Errors

Example

See also