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

# RCS API

> RCS Business Messaging brand registration, agents (bots), test devices, templates, and tester invites. Sending messages goes through the unified Messaging API.

# RCS API

RCS Business Messaging is the modern carrier-grade replacement for SMS on Android — rich cards, suggested replies, verified sender, read receipts. This surface registers your brand, creates verified agents, manages templates, and invites testers. Sending RCS messages themselves goes through the [Messaging API](/api-reference/endpoints/messaging) at `POST /api/v1/messages/rcs`.

**Base path:** `/api/v1/rcs`

**Authentication:** API key (`X-API-Key`) or session JWT.

## Brands

A **brand** is the customer-facing entity that owns one or more RCS agents. Brand verification with the carrier is required before launch.

| Method   | Path                             | Purpose                         |
| -------- | -------------------------------- | ------------------------------- |
| `POST`   | `/api/v1/rcs/brands`             | Create a brand                  |
| `GET`    | `/api/v1/rcs/brands`             | List brands                     |
| `GET`    | `/api/v1/rcs/brands/{id}`        | Get a brand                     |
| `PATCH`  | `/api/v1/rcs/brands/{id}`        | Update brand details            |
| `DELETE` | `/api/v1/rcs/brands/{id}`        | Delete brand                    |
| `POST`   | `/api/v1/rcs/brands/{id}/submit` | Submit for carrier verification |

## Agents (bots)

An RCS **agent** (sometimes called a "bot") is the actual sending identity — logo, color, contact info, and behavior. Agents must be verified before they can send to consumers.

| Method   | Path                           | Purpose                 |
| -------- | ------------------------------ | ----------------------- |
| `POST`   | `/api/v1/rcs/bots`             | Create an agent         |
| `GET`    | `/api/v1/rcs/bots`             | List agents             |
| `GET`    | `/api/v1/rcs/bots/{id}`        | Get an agent            |
| `PUT`    | `/api/v1/rcs/bots`             | Update agent profile    |
| `DELETE` | `/api/v1/rcs/bots/{id}`        | Delete an agent         |
| `POST`   | `/api/v1/rcs/bots/{id}/verify` | Submit for verification |

## Test devices

Add specific phone numbers that can receive messages from an unverified agent — used during integration and QA.

| Method   | Path                                  | Purpose                         |
| -------- | ------------------------------------- | ------------------------------- |
| `GET`    | `/api/v1/rcs/bots/{id}/devices`       | List test devices               |
| `POST`   | `/api/v1/rcs/bots/{id}/devices`       | Add a test device               |
| `DELETE` | `/api/v1/rcs/bots/{id}/devices`       | Remove a test device            |
| `POST`   | `/api/v1/rcs/bots/{id}/tester-invite` | Send a tester invite to a phone |

## Templates

Pre-approved message templates with rich card components, suggested replies, and quick actions.

| Method   | Path                                     | Purpose                |
| -------- | ---------------------------------------- | ---------------------- |
| `GET`    | `/api/v1/rcs/bots/{id}/templates`        | List templates         |
| `POST`   | `/api/v1/rcs/bots/{id}/templates`        | Create a template      |
| `GET`    | `/api/v1/rcs/bots/{id}/templates/{name}` | Get a template by name |
| `PUT`    | `/api/v1/rcs/bots/{id}/templates/{name}` | Update a template      |
| `DELETE` | `/api/v1/rcs/bots/{id}/templates/{name}` | Delete a template      |

## Commerce (catalog carousel)

Turn your product catalog into a shoppable RCS carousel. List the products available to send, then render a selection into a rich-card carousel where every card carries an **Add to cart** chip and the message carries a single **Checkout** chip. Sends go through the standard messaging pipeline, so billing, delivery receipts, and scheduling apply exactly as they do for any other RCS message.

Products come from the same Meta Commerce Manager catalog you connect for WhatsApp — one catalog serves both channels, so you do not configure a separate feed for RCS.

| Method | Path                                | Purpose                                       |
| ------ | ----------------------------------- | --------------------------------------------- |
| `GET`  | `/api/v1/rcs/commerce/catalog`      | List catalog products available to a carousel |
| `POST` | `/api/v1/rcs/commerce/send-catalog` | Send a catalog rich-card carousel             |

### List catalog products

Returns every product in your connected catalog. If no Commerce Manager catalog is connected yet, `data.products` is an empty array and `data.count` is `0` — an empty catalog is not an error, so your UI can render a "connect your catalog" empty state.

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/rcs/commerce/catalog \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "products": [
      {
        "id": "9xk2r7",
        "retailer_id": "SKU-001",
        "name": "Trailhead Daypack",
        "description": "22L weekender in recycled ripstop",
        "price": "89.00",
        "currency": "USD",
        "image_url": "https://cdn.example.com/daypack.jpg",
        "url": "https://shop.example.com/daypack",
        "availability": "in stock"
      }
    ],
    "count": 1
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-07-03T00:00:00.000Z" }
}
```

Each product's `retailer_id` is its SKU — that is the value you pass in `product_ids` when sending. Fields other than `id` are populated from Commerce Manager and may be absent for a given product.

### Send a catalog carousel

Renders the selected products into a carousel and sends it to one recipient. Each product becomes one card — name, price, description, and image — with an **Add to cart** chip; products that carry a link also get a **View** chip. A single message-level **Checkout** chip closes the flow.

| Field               | Type      | Notes                                                                                                                                   |
| ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `to`                | string    | Required. Recipient phone number in E.164 format.                                                                                       |
| `product_ids`       | string\[] | SKUs (`retailer_id`) to include, up to 50. Omit to send the whole catalog.                                                              |
| `body`              | string    | Message text shown above the carousel and used as the accessibility fallback (≤ 2000 chars). Defaults to a generic prompt when omitted. |
| `checkout_url`      | string    | HTTPS checkout link. When set, the Checkout chip opens this URL; otherwise Checkout is a reply you receive on your inbound webhook.     |
| `card_width`        | string    | `SMALL` or `MEDIUM` (default `MEDIUM`).                                                                                                 |
| `add_to_cart_label` | string    | Override the per-card Add-to-cart chip label (1–25 chars).                                                                              |
| `checkout_label`    | string    | Override the Checkout chip label (1–25 chars).                                                                                          |

A carousel needs at least 2 products and shows at most 10. If your selection resolves to fewer than 2 products — for example a `product_ids` list that matches nothing in the catalog — the request is rejected with `422`. A selection larger than 10 is truncated to the first 10 (the RCS carousel limit).

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/rcs/commerce/send-catalog \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "product_ids": ["SKU-001", "SKU-002", "SKU-003"],
    "body": "New arrivals just dropped",
    "checkout_url": "https://shop.example.com/checkout"
  }'
```

A successful send returns `202 Accepted` with the queued message:

```json theme={null}
{
  "data": {
    "id": "message_a1b2c3",
    "channel": "rcs",
    "direction": "outbound",
    "to": "+14155552671",
    "status": "queued"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-07-03T00:00:00.000Z" }
}
```

When a recipient taps **Add to cart** or **Checkout**, the tap arrives as an inbound RCS message on your configured webhook. Repeated Add-to-cart taps build the recipient's cart, and a Checkout tap signals intent to buy — handle these events in your webhook to complete the order.

## Capability check

Before sending RCS to a number, check whether the device + carrier supports it.

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/rcs/capability/bot_abc/+14155552671 \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

| Method | Path                                     | Purpose                          |
| ------ | ---------------------------------------- | -------------------------------- |
| `GET`  | `/api/v1/rcs/capability/{botId}/{phone}` | Probe RCS capability for a phone |

## Quality & analytics

Track how an agent is performing after launch: check its verification and per-carrier launch state, pull per-template and per-day engagement, and estimate how much of a segment can actually receive RCS before you spend on a campaign.

Per-template and per-day numbers are aggregated from your own delivery receipts, so they reflect the same `sent`/`delivered`/`read` timestamps you see on individual messages. Windows are measured in whole days ending now.

| Method | Path                              | Purpose                                        |
| ------ | --------------------------------- | ---------------------------------------------- |
| `GET`  | `/api/v1/rcs/bots/{id}/quality`   | Agent verification + per-carrier launch status |
| `GET`  | `/api/v1/rcs/analytics/templates` | Per-template delivery, read, and click rates   |
| `GET`  | `/api/v1/rcs/analytics/daily`     | Per-day sent / delivered / read volume         |
| `POST` | `/api/v1/rcs/reach-scan`          | Estimate a segment's RCS reach                 |

### Agent quality

Returns the verification and launch health of a single agent. Pass the agent's id as `{id}`. Responds `404` if no agent with that id exists in your account.

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/rcs/bots/bot_abc/quality \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "bot_id": "bot_abc",
    "display_name": "Acme Support",
    "brand_name": "Acme Inc",
    "status": "launched",
    "verification_status": "verified",
    "launched": true,
    "carrier_statuses": { "310260": { "status": "launched" } },
    "carriers_launched": 1,
    "carriers_total": 1
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-07-03T00:00:00.000Z" }
}
```

`launched` is `true` once the agent reaches a launched state overall or on at least one carrier. `carrier_statuses` echoes each carrier's raw status; `carriers_launched` and `carriers_total` summarise it so you can show "live on 1 of 2 carriers" without parsing the map.

### Template analytics

Returns one row per template sent over the RCS channel in the window, ordered by volume. Messages sent without a template name collapse into a single `(no template)` row.

| Query  | Type    | Notes                                       |
| ------ | ------- | ------------------------------------------- |
| `days` | integer | Window in days, `1`–`90`. Defaults to `30`. |

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/rcs/analytics/templates?days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": [
    {
      "template_name": "order_update",
      "sent": 1000,
      "delivered": 980,
      "read": 720,
      "clicked": 210,
      "delivery_rate": 98,
      "read_rate": 73,
      "click_rate": 21
    }
  ],
  "meta": { "request_id": "req_…", "timestamp": "2026-07-03T00:00:00.000Z" }
}
```

Rates are whole-number percentages: `delivery_rate` is `delivered / sent`, while `read_rate` and `click_rate` are over `delivered` (a handset cannot read or tap a card it never received).

### Daily analytics

Returns one row per day in the window, oldest first, with the day's RCS volume.

| Query  | Type    | Notes                                       |
| ------ | ------- | ------------------------------------------- |
| `days` | integer | Window in days, `1`–`90`. Defaults to `30`. |

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/rcs/analytics/daily?days=7" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": [
    { "date": "2026-06-27", "sent": 1200, "delivered": 1180, "read": 900 },
    { "date": "2026-06-28", "sent": 1340, "delivered": 1300, "read": 970 }
  ],
  "meta": { "request_id": "req_…", "timestamp": "2026-07-03T00:00:00.000Z" }
}
```

### Reach scan

Estimates what fraction of a saved contact segment can receive RCS through a given agent, so you can decide between RCS, a mixed RCS-with-SMS-fallback send, or plain SMS before you commit spend. It draws a bounded random sample from the segment and runs a live capability check for each sampled contact.

Requires the **owner**, **admin**, or **developer** role — it reads contact phone numbers and runs billable capability lookups.

| Field         | Type    | Notes                                              |
| ------------- | ------- | -------------------------------------------------- |
| `bot_id`      | string  | Required. Agent id to probe capability against.    |
| `segment_id`  | string  | Required. Id of the saved contact segment to scan. |
| `sample_size` | integer | Contacts to probe, `1`–`200`. Defaults to `50`.    |

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/rcs/reach-scan \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "bot_abc",
    "segment_id": "seg_123",
    "sample_size": 100
  }'
```

```json theme={null}
{
  "data": {
    "segment_id": "seg_123",
    "bot_id": "bot_abc",
    "sampled": 100,
    "capable": 76,
    "reach_percent": 76,
    "recommended_channel": "rcs"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-07-03T00:00:00.000Z" }
}
```

`sampled` is how many contacts were actually probed (contacts without a phone number, and probes that error out, are excluded, so it can be lower than `sample_size`). `reach_percent` is `capable / sampled`. `recommended_channel` is a suggestion derived from that reach: `rcs` at 70% or above, `mixed` from 30–69%, and `sms` below 30%. An unknown `bot_id` or `segment_id` responds `404`; a segment that resolves to no reachable contacts returns a zeroed summary rather than an error.

## Test account

A sandbox flow for first-time testers — verify your own phone via OTP, then receive sample messages from an unverified agent.

| Method | Path                                  | Purpose                          |
| ------ | ------------------------------------- | -------------------------------- |
| `GET`  | `/api/v1/rcs/test-account/status`     | Check test-account status        |
| `POST` | `/api/v1/rcs/test-account/send-otp`   | Send OTP to a phone              |
| `POST` | `/api/v1/rcs/test-account/verify-otp` | Verify OTP and enroll the device |

## See also

* [Channels → RCS guide](/channels/rcs) — concepts, regional availability, fallback strategy
* [Messaging API → Send RCS](/api-reference/endpoints/messaging)