> ## 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 agents

> Register RCS Business Messaging agents for an organization, link them to a Lua agent, and check which numbers can receive RCS

An RCS agent is the carrier-side sender identity (sender ID, display name, branding) an [organization](/concepts/credentials) uses for RCS Business Messaging. These routes register that identity, record which [agent](/concepts/agents) answers its messages, and check whether a phone number can receive RCS. For the channel setup, see [RCS](/channels/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](/reference/rest/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

<ResponseField name="id" type="string">RCS agent ID; use it in the path of the other routes.</ResponseField>
<ResponseField name="orgId" type="string">Owning organization.</ResponseField>
<ResponseField name="senderId" type="string">Carrier RBM sender ID. Unique across organizations.</ResponseField>
<ResponseField name="displayName" type="string">Name shown to recipients.</ResponseField>
<ResponseField name="description" type="string">Optional description.</ResponseField>
<ResponseField name="logoUrl" type="string">Logo image URL.</ResponseField>
<ResponseField name="bannerUrl" type="string">Banner image URL.</ResponseField>
<ResponseField name="status" type="string">One of `pending`, `testing`, `live`, `suspended`. Set with `PATCH`; the platform never advances it.</ResponseField>
<ResponseField name="webhookUrl" type="string">Inbound webhook URL stored on the record. This API does not register it with the carrier.</ResponseField>
<ResponseField name="capabilities" type="string[]">Reserved; always `[]`.</ResponseField>
<ResponseField name="geoAvailability" type="string[]">Regions where the agent is available, as free-form strings.</ResponseField>
<ResponseField name="createdBy" type="string">User ID of the creator.</ResponseField>
<ResponseField name="createdByEmail" type="string">Creator email, when known.</ResponseField>
<ResponseField name="linkedAgentId" type="string">The Lua agent recorded for this sender, once linked.</ResponseField>
<ResponseField name="createdAt" type="number">Unix time in milliseconds.</ResponseField>

## 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](#rcs-agent-object).

<ParamField body="senderId" type="string" required>The RBM sender ID issued by the carrier.</ParamField>
<ParamField body="displayName" type="string" required>Name shown to recipients.</ParamField>
<ParamField body="description" type="string">Description.</ParamField>
<ParamField body="logoUrl" type="string">Logo image URL.</ParamField>
<ParamField body="bannerUrl" type="string">Banner image URL.</ParamField>
<ParamField body="geoAvailability" type="string[]">Regions where the agent is available.</ParamField>

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

Lists the organization's RCS agents. Scope `telephony:read`.

<ParamField query="status" type="string">One of `pending`, `testing`, `live`, `suspended`.</ParamField>
<ParamField query="limit" type="number" default={50}>Maximum results.</ParamField>
<ParamField query="offset" type="number">Results to skip.</ParamField>

**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](#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.

<ParamField body="displayName" type="string">Name shown to recipients.</ParamField>
<ParamField body="description" type="string">Description.</ParamField>
<ParamField body="logoUrl" type="string">Logo image URL.</ParamField>
<ParamField body="bannerUrl" type="string">Banner image URL.</ParamField>
<ParamField body="status" type="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.</ParamField>
<ParamField body="webhookUrl" type="string">Inbound webhook URL to store.</ParamField>
<ParamField body="geoAvailability" type="string[]">Regions where the agent is available.</ParamField>

### 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](/channels/rcs).

<ParamField body="luaAgentId" type="string" required>The Lua agent ID.</ParamField>

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

<ParamField body="phoneNumber" type="string" required>The number to check, in E.164.</ParamField>

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

<ParamField body="phoneNumbers" type="string[]" required>Numbers in E.164.</ParamField>

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

<CodeGroup>
  ```ts TypeScript theme={null}
  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 ?? []);
  ```

  ```bash cURL theme={null}
  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" }'
  ```
</CodeGroup>

## See also

* [RCS](/channels/rcs) — set up the channel end to end
* [Phone numbers](/reference/rest/phone-numbers) — numbers and SMS compliance
* [Channels](/reference/rest/channels) — send messages over a channel
* [REST API overview](/reference/rest/overview) — authentication, scopes, errors