RCS Business Messaging

Preview

REST

Send Message

Send text, standalone rich cards, carousels, and suggested actions over RCS. Track delivery with GET /v1/rcs/status/:messageId and optional SMS fallback when RCS is unavailable.

Four payload types

text, richCard, carousel, and suggestedActions on a single send endpoint

Ghana number formatting

Accepts 024… / 055… / 233… and normalises to E.164 for routing

SMS fallback

Automatic degradation when the handset or network cannot accept RCS

Status + webhooks

Poll GET /v1/rcs/status/:messageId or subscribe to real-time events

Authentication

All REST requests use HTTP Basic Auth with your dashboard Base64 token: Authorization: Basic <token>. Auth guide →

Avg response

180ms

p95 accept time

Indicative cost

₵0.04+

RCS unit; SMS fallback extra if used

Max text length

3,072

characters (RCS text body)

Rate limit

80/s

per API key

POST

/v1/rcs/send

Core

Preview

Request body

application/json

JSON

{
  "to": "0555539152",
  "agentId": "AGT-SENDXA-GH",
  "type": "text",
  "text": {
    "body": "Hi Kofi — GHS 1,250.00 was credited to your wallet. Available balance: GHS 3,480.50. Ref: TXN-GH-88421."
  },
  "suggestions": [
    {
      "type": "reply",
      "text": "View balance",
      "postbackData": "balance"
    },
    {
      "type": "openUrl",
      "text": "Open app",
      "url": "https://app.sendexa.co/wallet"
    },
    {
      "type": "dial",
      "text": "Call support",
      "phoneNumber": "+233302555010"
    }
  ],
  "fallback": {
    "enabled": true,
    "channel": "sms",
    "from": "Sendexa",
    "message": "GHS 1,250.00 credited. Bal: GHS 3,480.50. Ref: TXN-GH-88421"
  },
  "reference": "wallet-credit-88421",
  "ttlSeconds": 86400
}

Suggestions are optional on text messages. Up to 11 chips may be shown depending on the client; keep labels ≤ 25 characters.

Top-level fields

Field	Type	Required	Description
to	string	required	Recipient MSISDN (Ghana local or international).
agentId	string	required	Approved RCS agent identifier.
type	string	required	text \| richCard \| carousel \| suggestedActions
text	object	optional	Required when type is text or suggestedActions.
richCard	object	optional	Required when type is richCard.
carousel	object	optional	Required when type is carousel.
suggestions	Suggestion[]	optional	Chip actions: reply \| openUrl \| dial. Required for suggestedActions.
fallback	object	optional	SMS fallback configuration when RCS cannot be delivered.
reference	string	optional	Your correlation ID (max 64 chars).
ttlSeconds	number	optional	Validity window. Default 86400 (24h).
webhookEnabled	boolean	optional	Override account default for delivery webhooks on this message.

Response

JSON

{
  "success": true,
  "code": "RCS_ACCEPTED",
  "message": "RCS message accepted for delivery.",
  "requestId": "REQ-1782002200912",
  "timestamp": "2026-07-12T10:02:00.912Z",
  "data": {
    "messageId": "MSG-RCS-a91f0c2e-8b44-4d11-9e20-6f3c1b0d8e77",
    "channel": "rcs",
    "agentId": "AGT-SENDXA-GH",
    "business": {
      "id": "BU-VOIF86X7",
      "name": "Letcol Technologies"
    },
    "message": {
      "to": {
        "address": "233555539152",
        "country": { "code": "GH", "name": "Ghana" },
        "network": "MTN"
      },
      "type": "text",
      "reference": "wallet-credit-88421"
    },
    "delivery": {
      "status": "QUEUED",
      "rcsCapable": null,
      "fallback": {
        "enabled": true,
        "channel": "sms",
        "triggered": false
      },
      "submittedAt": "2026-07-12T10:02:00.912Z",
      "expiresAt": "2026-07-13T10:02:00.912Z"
    },
    "billing": {
      "units": 1,
      "pricing": {
        "unitCost": 0.04,
        "totalCost": 0.04,
        "currency": "USD"
      }
    }
  }
}

Try it yourself

POST

https://api.sendexa.co/v1/rcs/send

Code examples

Bash

curl -X POST 'https://api.sendexa.co/v1/rcs/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "to": "0555539152",
    "agentId": "AGT-SENDXA-GH",
    "type": "text",
    "text": { "body": "Hello from Sendexa RCS!" },
    "fallback": {
      "enabled": true,
      "channel": "sms",
      "from": "Sendexa",
      "message": "Hello from Sendexa (SMS fallback)."
    }
  }'

Rate Limits

Burst limit for peak traffic

80 requests per second

Sustained rate limit

3000 requests per minute

Daily soft limit (raise via support)

50000 requests per day

HTTP status codes

Code	Status	Description
200	OK	Message accepted or status returned
400	Bad Request	Invalid phone, type, card, or carousel payload
401	Unauthorized	Invalid or missing Basic Auth token
403	Forbidden	Agent not approved, RCS disabled, or insufficient credits
404	Not Found	messageId not found on status lookup
429	Too Many Requests	Rate limit exceeded (80 requests/second)

GET

/v1/rcs/status/:messageId

Tracking

Poll delivery state, RCS capability, fallback channel, timestamps, and structured error details. Prefer webhooks for production; use this endpoint for reconciliation and support tooling.

Path parameters

Field	Type	Required	Description
messageId	string	required	ID returned from POST /v1/rcs/send (e.g. MSG-RCS-…).

Query parameters

Field	Type	Required	Description
includeHistory	boolean	optional	Include full status history timeline. Default false.
webhookStatus	boolean	optional	Include last webhook delivery attempt info. Default false.

Message lifecycle

queued

10:02:00

sent

10:02:01

delivered

10:02:04

Status response

JSON

{
  "success": true,
  "data": {
    "messageId": "MSG-RCS-a91f0c2e-8b44-4d11-9e20-6f3c1b0d8e77",
    "status": "read",
    "channel": "rcs",
    "agentId": "AGT-SENDXA-GH",
    "recipient": "233555539152",
    "type": "text",
    "reference": "wallet-credit-88421",
    "rcsCapable": true,
    "submittedAt": "2026-07-12T10:02:00.912Z",
    "sentAt": "2026-07-12T10:02:01.200Z",
    "deliveredAt": "2026-07-12T10:02:04.010Z",
    "readAt": "2026-07-12T10:03:18.440Z",
    "lastUpdatedAt": "2026-07-12T10:03:18.440Z",
    "errorCode": null,
    "errorMessage": null,
    "network": "MTN",
    "fallback": {
      "enabled": true,
      "triggered": false
    }
  }
}

Delivery status legend

queued

Accepted by Sendexa; waiting for RCS route

sent

Submitted to RCS network / carrier path

delivered

Delivered to the device messaging app

read

User opened the conversation (when available)

failed

Terminal failure — see errorCode / fallback state

Error code reference

Code	Message	Resolution
INVALID_PHONE	Invalid destination number	Normalise to local or E.164 Ghana format
AGENT_NOT_APPROVED	Agent not ready for traffic	Complete agent verification
RCS_UNREACHABLE	No RCS path and no fallback	Enable SMS fallback for critical traffic
MEDIA_FETCH_FAILED	Could not fetch media URL	Use public HTTPS CDN URLs
INSUFFICIENT_CREDITS	Balance too low	Top up account balance
TTL_EXPIRED	Message expired before delivery	Resend with higher ttlSeconds

Status code examples

Bash

curl -X GET 'https://api.sendexa.co/v1/rcs/status/MSG-RCS-a91f0c2e-8b44-4d11-9e20-6f3c1b0d8e77?includeHistory=true' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN'

Common use cases (Ghana / Africa)

OTP

Two-factor authentication

Send codes as RCS text with SMS fallback so login never fails on non-RCS devices.

Payments

Wallet & MoMo alerts

Branded credit/debit receipts with openUrl to statements and dial for support.

Commerce

Catalogues & promos

Carousel of products with Buy links — ideal for retail and marketplace campaigns.

Best practices

Always persist messageId and optional reference.
Enable SMS fallback for OTPs, transfers, and SLA-bound alerts.
Use webhooks instead of tight status polling loops.
For rich layouts, follow media size and height guidance in Rich Cards & Media.
Implement exponential backoff on HTTP 429.

Send Message

Four payload types

Ghana number formatting

SMS fallback

Status + webhooks

Authentication

Request body

Top-level fields

Response

Try it yourself

Code examples

Rate Limits

HTTP status codes

Path parameters

Query parameters

Message lifecycle

Status response

Delivery status legend

Error code reference

Status code examples

Common use cases (Ghana / Africa)

Best practices

Related docs