Send Your First RCS Rich Message End to End

Onboarding an RCS agent ends at the launch gate — the agent is live, but no message has left it yet. This guide closes that gap with one minimal walk: author and approve a rich-card template, prove the tester device can receive it, send it through your agent, and watch the delivery receipt land on a webhook. Everything here is the single-send version of campaign-scale work; when you scale to a segment, the RCS campaign playbook takes over. If you have not launched an agent yet, run the RCS onboarding guide first — the brand → agent → verify → launch gates happen there, and this walk fails its first send until the agent is launched.

1. Prerequisites

A launched agent (bot). The agent must show launched on at least one carrier in GET /api/v1/rcs/bots/:id/quality. If you are still evaluating without a full brand path, the built-in test account from the RCS onboarding guide substitutes for this walk.
A tester device on the agent’s tester list. While the agent is still pre-launch, only registered tester handsets can receive — POST /api/v1/rcs/bots/:id/devices (direct registration) or the tester-invite flow. Keep the E.164 number you registered; it is the recipient for every step below.
An API key. Copy it from the dashboard; every call below carries it as X-API-Key.

2. Author and approve a template

Rich sends reference a stored template that carriers screen for content before it can leave the platform. Author the definition, submit it for review, and wait for the Approved badge before you send. The visual way to do this is the Studio template editor on Messages → RCS → Builder — pick the rich-card template kind (card with a title, description, and a mediaUrl); the Rich Card Studio guide walks the editor end to end. Here, to keep the walk short, create the same rich card directly over the API:

curl -X POST "https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4kqzx1/templates" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rich_template_data": {
      "name": "first_card",
      "title": "Your order shipped",
      "body": "Package is on the way — goodbye, guessing.",
      "media_url": "https://cdn.acmeretail.com/rcs/first-card.png"
    }
  }'

The response carries the stored template with an rcs_tpl_... identifier and a pending_review status. Fetch GET /api/v1/rcs/bots/:id/templates/:name until it reads Approved; the Templates tab shows the same badge inline with the deliverability counters. A PUT after approval resets the template to pending, so treat approval as a final gate before the walk continues.

3. Check the recipient before you send

RCS capability is per device and per agent — a recipient capable for Agent A can be unreachable for Agent B. Probe before sending:

curl "https://api.orbit.devotel.io/api/v1/rcs/capability/bot_4kqzx1/+14155550123" \
  -H "X-API-Key: dv_live_sk_..."

Response — 200:

{
  "data": {
    "isCapable": true,
    "universalProfileVersion": "3.0",
    "featureFlags": { "mlsSupported": true, "richLinkSupported": true }
  }
}

Gate on isCapable: true; a false (with fallback: "sms") means the handset is not RBM-reachable through this agent and you should send the SMS copy shown in the RCS fallback and capability concept page — a skipped probe lands the send as a terminal RCS_NOT_SUPPORTED, the failure this walk exists to avoid.

4. Send the rich card

With the template approved and the recipient confirmed capable, send one message:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/rcs" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "rich_card": {
      "card_content": {
        "title": "Your order shipped",
        "description": "Package is on the way — goodbye, guessing.",
        "media": {
          "height": "MEDIUM",
          "content_info": { "file_url": "https://cdn.acmeretail.com/rcs/first-card.png" }
        }
      }
    }
  }'

const res = await fetch("https://api.orbit.devotel.io/api/v1/messages/rcs", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155550123",
    rich_card: {
      card_content: {
        title: "Your order shipped",
        description: "Package is on the way — goodbye, guessing.",
        media: {
          height: "MEDIUM",
          content_info: { file_url: "https://cdn.acmeretail.com/rcs/first-card.png" },
        },
      },
    },
  }),
});
if (res.status !== 202) throw new Error(await res.text());
const { data } = await res.json();
console.log(data.id); // msg_... — keep this for step 5

import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/messages/rcs",
    headers={"X-API-Key": "dv_live_sk_..."},
    json={
        "to": "+14155550123",
        "rich_card": {
            "card_content": {
                "title": "Your order shipped",
                "description": "Package is on the way — goodbye, guessing.",
                "media": {
                "height": "MEDIUM",
                "content_info": {"file_url": "https://cdn.acmeretail.com/rcs/first-card.png"},
            },
            }
        },
    },
)
assert res.status_code == 202, res.text
message_id = res.json()["data"]["id"]
print(message_id)  # msg_... — keep this for step 5

The response is 202 with the message identifier as msg_... — keep it; the webhook events in step 5 key on it. Inline rich cards like the example send instantly; the cleaner production shape sends the approved template by name through a campaign — the RCS channel page covers every body field, and its rich_card_carousel sibling takes 2–10 cards in one send.

5. Read the delivery lifecycle over a webhook

A 202 means the message is accepted for delivery, not delivered. Register one receiver and subscribe to the two outcomes that resolve an RCS first-send:

curl -X POST "https://api.orbit.devotel.io/api/v1/webhooks" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example/hooks/orbit",
    "events": ["message.delivered", "message.failed"]
  }'

The receiver shape — verify the signature, handle the event, enqueue retries on failure — is covered in the durable webhook consumer guide. A delivered rich card arrives as a normalized envelope; the events catalog lists the full vocabulary on the webhook events page:

{
  "event": "message.delivered",
  "data": {
    "id": "msg_9f3c8a12",
    "channel": "rcs",
    "status": "delivered",
    "delivered_at": "2026-09-23T14:11:02Z"
  }
}

RCS also reports message.read — the open receipt SMS never produces — so subscribe to it when you are past first-send debugging and want engagement data.

6. Troubleshoot the three predictable failures

First RCS sends usually die in one of three ways; each resolves to a specific pre-send gate:

Code	Cause	Fix
`INVALID_LAUNCH_STATE` (409)	The agent is not `launched` on any carrier — onboarding is not through gate 4.	Poll `GET /api/v1/rcs/bots/:id/quality` until `carrier_statuses` shows `launched`; sending while `pending_launch` answers this.
Template not approved (422)	The template id names a draft — `PUT` after approval reset it to pending, or it was never submitted.	Resolve the template against the agent’s roster and confirm the badge reads `Approved` on the Templates tab; re-submit and wait.
`RCS_NOT_SUPPORTED` (terminal failure)	The capability check was skipped and the handset is not RBM-reachable.	Gate on `isCapable: true` from `GET /api/v1/rcs/capability/:botId/:recipient` before every send; route `fallback: "sms"` recipients down the SMS path instead.

For deeper diagnosis — carrier rejections, delivery-dips, capability drift — the RCS undelivered troubleshooting page reads the classified error code off GET /api/v1/messages/:id so you can attach cause to outcome without re-sending traffic.

7. Next steps

Scale the same card to a segment in the RCS campaign playbook — reach scan, ladder fallback, dry-run, and launch are the campaign version of steps 2–4.
Read the RCS channel page for carousels, suggested actions, and the fallback chain concept.
Cover the durable receiver pattern in the webhook consumer guide before your first production rollout.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Send your first RCS rich message end to end

Send Your First RCS Rich Message End to End

1. Prerequisites

2. Author and approve a template

3. Check the recipient before you send

4. Send the rich card

5. Read the delivery lifecycle over a webhook

6. Troubleshoot the three predictable failures

7. Next steps

​Send Your First RCS Rich Message End to End

​1. Prerequisites

​2. Author and approve a template

​3. Check the recipient before you send

​4. Send the rich card

​5. Read the delivery lifecycle over a webhook

​6. Troubleshoot the three predictable failures

​7. Next steps

Send Your First RCS Rich Message End to End

1. Prerequisites

2. Author and approve a template

3. Check the recipient before you send

4. Send the rich card

5. Read the delivery lifecycle over a webhook

6. Troubleshoot the three predictable failures

7. Next steps