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 at POST /api/v1/messages/rcs. Base path: /api/v1/rcs Authentication: API key (X-API-Key) or session JWT.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.rcs.list();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/rcs")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

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

These endpoints manage the brand and agent registry — they never deliver content to end users. Message sends go through the Messaging API.

Create a brand

The brand carries the identity and KYC details carriers ask for before a bot can message their subscribers. Creating a brand does not start the review: patch it until it is complete, then submit it.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/brands \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "Acme Retail Co",
    "brand_website": "https://www.example.com",
    "brand_logo_url": "https://cdn.example.com/logo.png",
    "industry_vertical": "Retail",
    "contact_first_name": "Jana",
    "contact_last_name": "Ortiz",
    "contact_email": "jana@example.com",
    "contact_phone": "+14155550123",
    "address_line_1": "100 Market Street",
    "city": "San Francisco",
    "state_province": "CA",
    "country": "US",
    "postal_code": "94105"
  }'

{
  "data": {
    "id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
    "brandName": "Acme Retail Co",
    "brandWebsite": "https://www.example.com",
    "brandLogoUrl": "https://cdn.example.com/logo.png",
    "industryVertical": "Retail",
    "contactFirstName": "Jana",
    "contactLastName": "Ortiz",
    "contactEmail": "jana@example.com",
    "contactPhone": "+14155550123",
    "contactDesignation": null,
    "addressLine1": "100 Market Street",
    "addressLine2": null,
    "city": "San Francisco",
    "stateProvince": "CA",
    "country": "US",
    "postalCode": "94105",
    "taxId": null,
    "legalEntityName": null,
    "status": "draft",
    "dotgoBrandId": null,
    "rejectionReason": null,
    "submittedAt": null,
    "submittedToDotgoAt": null,
    "approvedAt": null,
    "createdAt": "2026-09-03T10:12:00.000Z",
    "updatedAt": "2026-09-03T10:12:00.000Z"
  },
  "meta": {
    "request_id": "req_90b2c1",
    "timestamp": "2026-09-03T10:12:00.000Z"
  }
}

data.id is the brand id you pass to the read, update, submit and delete endpoints. A blank or off-contract field is rejected with 422 listing the fields that failed validation.

List brands

Cursor-paginated. The list projection is deliberately lean — name, website, industry, country, status and the contact’s display name; the full KYC record comes back on GET /rcs/brands/{id}.

curl "https://api.orbit.devotel.io/api/v1/rcs/brands?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
      "brandName": "Acme Retail Co",
      "brandWebsite": "https://www.example.com",
      "brandLogoUrl": "https://cdn.example.com/logo.png",
      "industryVertical": "Retail",
      "contactFirstName": "Jana",
      "contactLastName": "Ortiz",
      "country": "US",
      "status": "approved",
      "dotgoBrandId": "dgt_brand_7711",
      "rejectionReason": null,
      "submittedAt": "2026-09-03T10:15:21.000Z",
      "createdAt": "2026-09-03T10:12:00.000Z",
      "updatedAt": "2026-09-03T10:20:11.000Z"
    }
  ],
  "meta": {
    "request_id": "req_90b2c2",
    "timestamp": "2026-09-03T10:12:30.000Z",
    "pagination": { "cursor": "c1Ysfnexdg", "has_more": true }
  }
}

Pass meta.pagination.cursor as ?cursor= to fetch the next page, 1–200 per page (50 by default). has_more: true tells you another page exists.

Submit a brand for carrier verification

Hand the complete brand to verification. Submissions are the carrier’s review gate, so call this only after the record is complete — a refusal lands as rejected with a rejection_reason, and you can PATCH /rcs/brands/{id} and submit again.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/brands/8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f/submit \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
    "brandName": "Acme Retail Co",
    "brandWebsite": "https://www.example.com",
    "brandLogoUrl": "https://cdn.example.com/logo.png",
    "industryVertical": "Retail",
    "contactFirstName": "Jana",
    "contactLastName": "Ortiz",
    "contactEmail": "jana@example.com",
    "contactPhone": "+14155550123",
    "contactDesignation": null,
    "addressLine1": "100 Market Street",
    "addressLine2": null,
    "city": "San Francisco",
    "stateProvince": "CA",
    "country": "US",
    "postalCode": "94105",
    "taxId": null,
    "legalEntityName": null,
    "status": "pending_review",
    "dotgoBrandId": null,
    "rejectionReason": null,
    "submittedAt": "2026-09-03T10:15:21.000Z",
    "submittedToDotgoAt": null,
    "approvedAt": null,
    "createdAt": "2026-09-03T10:12:00.000Z",
    "updatedAt": "2026-09-03T10:15:21.000Z"
  },
  "meta": {
    "request_id": "req_90b2c3",
    "timestamp": "2026-09-03T10:15:21.000Z"
  }
}

The returned brand carries the full record; fields not shown here keep their values from creation. status moves to pending_review; poll GET /rcs/brands/{id} for the approved (or rejected with rejection_reason) outcome.

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

The agent endpoints manage the verified sender registry — sending to consumers goes through the Messaging API.

Create an agent

Register the agent subscribers see in their messaging app against one of your brands. brand_id points at a brand you created above (rejected or suspended brands are refused with 409; every other state is submittable). Pass a display_name, a description of 100 characters or fewer, HTTPS tos_url and privacy_policy_url, at least one of contact_phone / contact_email, and a non-empty carrier_mccmnc list of the 5–6-digit carrier codes it targets — the directory rejects a submission missing any of them. Optional bot_type (OTP, Transactional, Promotional, Multi-Use — case-sensitive), region, platform, billing_category, and a creation_data free-form object for agent styling like logo and colors.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/bots \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
    "display_name": "Acme Support",
    "description": "Answers order and delivery questions for Acme Retail",
    "website": "https://www.example.com",
    "contact_email": "support@example.com",
    "tos_url": "https://www.example.com/terms",
    "privacy_policy_url": "https://www.example.com/privacy",
    "bot_type": "Transactional",
    "carrier_mccmnc": ["310260"],
    "region": "Rest of World",
    "creation_data": {
      "logo_url": "https://cdn.example.com/agent-logo.png",
      "agent_color": "#0A7F5A",
      "banner_image_url": "https://cdn.example.com/agent-banner.png"
    }
  }'

{
  "data": {
    "localId": "bot_4fa0c12b",
    "dotgoResponse": {
      "bot_id": "dgt_bot_8842",
      "bot_status": "SUBMITTED"
    }
  },
  "meta": {
    "request_id": "req_90b2c4",
    "timestamp": "2026-09-03T10:16:02.000Z"
  }
}

data.localId is the agent id you pass to the read, update, verification, template, device and quality endpoints. A missing or off-contract field is rejected with 422 before the directory is ever called.

Get an agent

curl https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4fa0c12b \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "bot_4fa0c12b",
    "dotgoBotId": "dgt_bot_8842",
    "brandId": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
    "brandName": "Acme Retail Co",
    "displayName": "Acme Support",
    "description": "Answers order and delivery questions for Acme Retail",
    "website": "https://www.example.com",
    "logoUrl": "https://cdn.example.com/agent-logo.png",
    "contactPhone": null,
    "contactEmail": "support@example.com",
    "tosUrl": "https://www.example.com/terms",
    "privacyPolicyUrl": "https://www.example.com/privacy",
    "botType": "Transactional",
    "status": "created",
    "verificationStatus": "created",
    "carrierStatuses": { "310260": { "status": "pending" } },
    "config": { "carrier_mccmnc": ["310260"], "region": "Rest of World" },
    "createdAt": "2026-09-03T10:16:02.000Z",
    "updatedAt": "2026-09-03T10:16:02.000Z",
    "templateCount": 2
  },
  "meta": {
    "request_id": "req_90b2c5",
    "timestamp": "2026-09-03T10:16:12.000Z"
  }
}

An unknown id responds 404. templateCount is the number of templates this agent carries (see the Templates section below).

Update agent basics

PUT /rcs/bots re-submits the creation payload in place — it accepts the same structured fields as creation, plus creation_data for the public directory record. Send the fields you want to change; the remainder keep their values.

curl -X PUT https://api.orbit.devotel.io/api/v1/rcs/bots \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
    "display_name": "Acme Support",
    "description": "Answers order and delivery questions for Acme Retail",
    "website": "https://www.example.com",
    "contact_email": "support@example.com",
    "tos_url": "https://www.example.com/terms",
    "privacy_policy_url": "https://www.example.com/privacy",
    "carrier_mccmnc": ["310260"]
  }'

{
  "data": {
    "localId": "bot_4fa0c12b",
    "dotgoResponse": {
      "bot_id": "dgt_bot_8842",
      "bot_status": "SUBMITTED"
    }
  },
  "meta": {
    "request_id": "req_90b2c6",
    "timestamp": "2026-09-03T10:16:40.000Z"
  }
}

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

Add a test device

Enrolls a handset’s E.164 number as an approved tester for an agent while the agent is still unverified, so QA and integration traffic can reach it. Once the agent launches, real recipients no longer need enrollment.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4fa0c12b/devices \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155552671" }'

{
  "data": {
    "phone": "+14155552671",
    "added": true
  },
  "meta": {
    "request_id": "req_90b2c7",
    "timestamp": "2026-09-03T10:17:05.000Z"
  }
}

Most carriers additionally require the handset to accept a carrier tester invite before messages arrive. POST /rcs/bots/{id}/tester-invite with the same { "phone" } body sends that invite; the device shows up under GET /rcs/bots/{id}/devices once it accepts. To remove a tester, call DELETE /rcs/bots/{id}/devices with the same body — it answers 204 with an empty body.

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

Templates are submitted for approval on the agent-management plane — a template does not send a message. Send approved templates through the Messaging API at render time.

Create a template

Body accepts a single rich_template_data object holding the rich-card or carousel definition, including the name that identifies the template on later reads, updates, and sends. type is rich_card for a single card and carousel when the payload wraps several cards; any deep-link action inside needs a valid deepLink and fallbackUrl (https://), rejected with 422 before the template reaches the platform. Approval starts as pending.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4fa0c12b/templates \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rich_template_data": {
      "name": "order_update",
      "type": "rich_card",
      "card": {
        "title": "Your order has shipped",
        "subtitle": "Order #4821 — delivery estimate Thursday",
        "media": { "url": "https://cdn.example.com/order-card.jpg" },
        "suggestions": [
          { "text": "Track package", "action": { "type": "openurl", "url": "https://www.example.com/track/4821" } },
          { "text": "Contact us", "reply": "SUPPORT" }
        ]
      }
    }
  }'

A carousel submission uses the same envelope with "type": "carousel" and a cards array of rich cards inside rich_template_data.

{
  "data": {
    "name": "order_update",
    "status": "pending",
    "submitted": true
  },
  "meta": {
    "request_id": "req_90b2c8",
    "timestamp": "2026-09-03T10:18:11.000Z"
  }
}

Read, update, and delete a template

Templates are keyed by {name} inside the agent. Read one:

curl https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4fa0c12b/templates/order_update \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "name": "order_update",
    "status": "approved",
    "rich_template_data": {
      "type": "rich_card",
      "card": {
        "title": "Your order has shipped",
        "subtitle": "Order #4821 — delivery estimate Thursday"
      }
    }
  },
  "meta": {
    "request_id": "req_90b2c9",
    "timestamp": "2026-09-03T10:18:12.000Z"
  }
}

Update a template in place — the body mirrors creation (PUT onto /templates/{name}):

curl -X PUT https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4fa0c12b/templates/order_update \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "rich_template_data": { "name": "order_update", "type": "rich_card", "card": { "title": "Your order has shipped" } } }'

Delete a template — the endpoint answers 204 with an empty body:

curl -X DELETE https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4fa0c12b/templates/order_update \
  -H "X-API-Key: dv_live_sk_your_key_here"

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.

curl https://api.orbit.devotel.io/api/v1/rcs/commerce/catalog \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "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).

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:

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

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.

curl https://api.orbit.devotel.io/api/v1/rcs/bots/bot_abc/quality \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "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`.

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

{
  "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`.

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

{
  "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`.

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
  }'

{
  "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

The test account is a sandbox for first-time testers on unverified agents. It targets your own handset through Devotel’s shared demo bot with a bounded quota — not production traffic. Production sends go through your verified agent via the Messaging API; the test-account endpoints are rejected for a verified agent.

Send the OTP

Start verification on your handset: the number’s RCS capability is probed, it is registered as a tester device on the shared demo bot, and the carrier tester invite is delivered. Pass any common formatting; the number must resolve to E.164, and a handset with no RCS support is rejected instead of being registered. Owner / admin / developer roles only, a handful of attempts per 10-minute window per organization.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/test-account/send-otp \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550123" }'

{
  "data": {
    "verification_id": "rcsver_8f2c41ab9d",
    "expires_in": 600,
    "rcs_capable": true,
    "verification_mode": "tester_invite_acceptance"
  },
  "meta": {
    "request_id": "req_90b2ca",
    "timestamp": "2026-09-03T10:19:01.000Z"
  }
}

Verify the OTP

Acceptance happens on the handset — when the carrier tester invite is accepted, verification completes. This endpoint re-checks that state; call it with the verification_id from send-otp. While the invite is still pending it answers 425 PENDING_ACCEPTANCE (retry every few seconds — the dashboard polls for up to ten minutes); a declined invite answers 422 INVITE_DECLINED; an unknown or expired session answers 422 — start again at send-otp in either case. The deprecated code field is accepted for older clients and ignored.

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/test-account/verify-otp \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "verification_id": "rcsver_8f2c41ab9d" }'

{
  "data": {
    "verified": true,
    "phone": "+14155550123"
  },
  "meta": {
    "request_id": "req_90b2cb",
    "timestamp": "2026-09-03T10:19:04.000Z"
  }
}

A still-pending session:

425

{
  "error": {
    "code": "PENDING_ACCEPTANCE",
    "message": "The tester invite has not been accepted on the handset yet — keep polling.",
    "status": 425
  },
  "meta": {
    "request_id": "req_90b2cb",
    "timestamp": "2026-09-03T10:19:04.000Z"
  }
}

API Reference

All Endpoints

RCS API: brand registration, agents, templates, testers

RCS API

Using the SDKs

Brands

Create a brand

List brands

Submit a brand for carrier verification

Agents (bots)

Create an agent

Get an agent

Update agent basics

Test devices

Add a test device

Templates

Create a template

Read, update, and delete a template

Commerce (catalog carousel)

List catalog products

Send a catalog carousel

Capability check

Quality & analytics

Agent quality

Template analytics

Daily analytics

Reach scan

Test account

Send the OTP

Verify the OTP

See also

​RCS API

​Using the SDKs

​Brands

​Create a brand

​List brands

​Submit a brand for carrier verification

​Agents (bots)

​Create an agent

​Get an agent

​Update agent basics

​Test devices

​Add a test device

​Templates

​Create a template

​Read, update, and delete a template

​Commerce (catalog carousel)

​List catalog products

​Send a catalog carousel

​Capability check

​Quality & analytics

​Agent quality

​Template analytics

​Daily analytics

​Reach scan

​Test account

​Send the OTP

​Verify the OTP

​See also

RCS API

Using the SDKs

Brands

Create a brand

List brands

Submit a brand for carrier verification

Agents (bots)

Create an agent

Get an agent

Update agent basics

Test devices

Add a test device

Templates

Create a template

Read, update, and delete a template

Commerce (catalog carousel)

List catalog products

Send a catalog carousel

Capability check

Quality & analytics

Agent quality

Template analytics

Daily analytics

Reach scan

Test account

Send the OTP

Verify the OTP

See also