All RCS messages go through a single endpoint: 
POST /v1/messages
The request body determines the content shape and billing unit. Every send requires an approved production agent and a phone number that is RCS-capable (checked automatically at send time).
Device capability is checked automatically. If the device is not RCS-capable, the send returns 404. In campaign flows, this triggers the configured failure branch (e.g. SMS fallback).

​
Required fields (all RCS sends)

​
Authorization
string
required
Bearer <api_key>
​
Idempotency-Key
string
UUID. Include on every send to prevent duplicates on retry.
​
agent_id
string
required
Your approved production agent id (e.g. ag_live_xxxx). The agent must be in APPROVED status and launched on at least one carrier.
​
to
string
required
Destination phone number in international format (e.g. +4917612345678).
​
message_type
string
required
Controls billing path and allowed content:
ValueWhen to use
MESSAGEStandard one-shot send (text, rich card, carousel)
CONVERSATIONFollow-up within an active 24-hour user session
NEWSLETTEROpted-in bulk sends with MAU billing
​
traffic_type
string
required
Regulatory classification per send. Must be permitted by your agent’s use_case.
ValueTypical use
AUTHENTICATIONOTP and auth codes
TRANSACTIONDelivery alerts, account notifications
PROMOTIONMarketing and offers
SERVICEREQUESTService messages the user consented to receive
ACKNOWLEDGEMENTConfirming an unsubscribe or opt-out
traffic_type names do not match use_case names one-to-one. For example, the TRANSACTIONAL use_case maps to TRANSACTION (not TRANSACTIONAL), and PROMOTIONAL maps to PROMOTION. Sending a traffic_type not permitted by your agent’s use_case results in carrier rejection. Use MULTI_USE on your agent for the broadest coverage. See the mapping table.
​
ttl
string
Optional delivery expiry as a duration string (e.g. "3600s"). The message is automatically revoked if not delivered within this window. Useful for time-sensitive content like flash offers.

​
Plain text — Basic Message

Short text with no suggestions. Maximum 3,072 characters. 
curl -sS -X POST "https://api.arowana.app/v1/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_live_xxxx",
    "to": "+4917612345678",
    "message_type": "MESSAGE",
    "content": {
      "text": "Your order #1234 has shipped and will arrive tomorrow."
    },
    "traffic_type": "TRANSACTION"
  }'
Text ≤ 160 UTF-8 chars with no suggestions → Basic Message billing.
Text > 160 chars → Single Message billing.

​
Text with suggestions — Single Message

Adding any suggestion chip (reply or action) forces Single Message billing, regardless of text length. Maximum 11 suggestion chips per message. 
{
  "agent_id": "ag_live_xxxx",
  "to": "+4917612345678",
  "message_type": "MESSAGE",
  "content": {
    "text": "Your order is out for delivery. Need anything?",
    "suggestions": [
      {
        "reply": {
          "text": "Track order",
          "postback_data": "dHJhY2tfMTIzNA=="
        }
      },
      {
        "action": {
          "text": "Call support",
          "dial": { "phone_number": "+4930123456" }
        }
      }
    ]
  },
  "traffic_type": "TRANSACTION"
}
postback_data must be base64-encoded. When the user taps a suggested reply, the platform fires a conversation.started webhook with this value in data.user_message.postback_data.

​
Rich card — Single Message

A standalone card with image, title, description, and up to 4 suggestion chips. 
{
  "agent_id": "ag_live_xxxx",
  "to": "+4917612345678",
  "message_type": "MESSAGE",
  "content": {
    "rich_card": {
      "standalone": {
        "orientation": "VERTICAL",
        "content": {
          "title": "Summer Sale — 50% off",
          "description": "Shop our biggest sale of the year. This weekend only.",
          "media": {
            "url": "https://cdn.arowana.app/summer-sale.jpg",
            "height": "TALL"
          },
          "suggestions": [
            {
              "action": {
                "text": "Shop now",
                "open_url": { "url": "https://shop.arowana.app/sale" }
              }
            }
          ]
        }
      }
    }
  },
  "traffic_type": "PROMOTION"
}
See RCS rich card for the full field reference including media heights, orientation, and all action types.
A horizontal scroll of 2–10 cards, each with up to 4 suggestion chips. 
{
  "agent_id": "ag_live_xxxx",
  "to": "+4917612345678",
  "message_type": "MESSAGE",
  "content": {
    "rich_card": {
      "carousel": {
        "card_width": "MEDIUM",
        "cards": [
          {
            "title": "Running Shoes",
            "description": "Lightweight and responsive.",
            "media": { "url": "https://cdn.arowana.app/shoes.jpg", "height": "MEDIUM" },
            "suggestions": [
              { "action": { "text": "View", "open_url": { "url": "https://shop.arowana.app/shoes" } } }
            ]
          },
          {
            "title": "Trail Jacket",
            "description": "Waterproof, packable.",
            "media": { "url": "https://cdn.arowana.app/jacket.jpg", "height": "MEDIUM" },
            "suggestions": [
              { "action": { "text": "View", "open_url": { "url": "https://shop.arowana.app/jacket" } } }
            ]
          }
        ]
      }
    }
  },
  "traffic_type": "PROMOTION"
}
See RCS carousel for the full field reference.

​
Send response

All successful sends return the same shape: 
{
  "message_id": "msg_a1b2c3d4",
  "status": "queued",
  "created_at": "2026-03-28T09:00:00Z",
  "billing": {
    "channel": "RCS",
    "message_type": "single_message",
    "hold_amount": 0.10,
    "message_price": 0.10,
    "balance": { "free": 49.90, "reserved": 0.10, "total": 50.00 },
    "tier": { "channel": "RCS", "current": "tier_1", "volume_used": 1251 }
  }
}
status: "queued" means the message was accepted — not delivered. Track delivery via webhooks or GET /v1/messages/{id}.

​
What to do next

Track delivery

Get notified when your message is delivered, read, or fails.

Receive replies

Handle inbound user replies and open conversation sessions.

RCS agents

Agent lifecycle, approval, and newsletter enablement.