Carousel layouts send multiple rich cards in a single scrollable message — product grids, multiple offers, or selectable options. Always billed as Single Message.

​
Request

​
Authorization
string
required
Bearer <api_key>
​
Idempotency-Key
string
UUID to prevent duplicate sends on retry.

​
Body

{
  "to": "+4917612345678",
  "agent_id": "ag_live_xxxx",
  "message_type": "MESSAGE",
  "content": {
    "rich_card": {
      "carousel": {
        "card_width": "MEDIUM",
        "cards": [
          {
            "title": "Product A",
            "description": "Premium quality — limited stock",
            "media": { "url": "https://cdn.arowana.app/a.jpg", "height": "MEDIUM" },
            "suggestions": [
              { "reply": { "text": "Select A", "postback_data": "select_product_a" } }
            ]
          },
          {
            "title": "Product B",
            "description": "Best value this week",
            "media": { "url": "https://cdn.arowana.app/b.jpg", "height": "MEDIUM" },
            "suggestions": [
              { "reply": { "text": "Select B", "postback_data": "select_product_b" } }
            ]
          }
        ]
      }
    }
  },
  "traffic_type": "PROMOTION"
}
​
to
string
required
Destination phone number in international format (e.g. +4917612345678).
​
agent_id
string
required
Approved production agent id.
​
message_type
string
required
MESSAGE for one-shot sends.
​
content.rich_card.carousel.card_width
string
Width of each card: SMALL (120 dp) or MEDIUM (232 dp). Controls how many cards are visible in the initial viewport.
​
content.rich_card.carousel.cards
array
required
Array of card objects. Minimum 2, maximum 10 cards.Each card supports:
  • title — max 200 characters
  • description — max 2,000 characters
  • media — image/video with url, optional thumbnail_url, and height (SHORT, MEDIUM, TALL)
  • suggestions — up to 4 suggestions per card. Each is a reply (text max 25 chars, postback_data must be base64-encoded, max 2048 chars) or an action (text max 25 chars, optional fallback_url). Action types: dial, open_url, open_url_in_webview, view_location, share_location, create_calendar_event. open_url and open_url_in_webview accept only https:// or http:// URLs.
​
ttl
string
Optional delivery expiry as a duration string (e.g. "3600s"). Message is automatically revoked if not delivered within this window.
​
traffic_type
string
required
Regulatory classification. Values: AUTHENTICATION, TRANSACTION, PROMOTION, SERVICEREQUEST, ACKNOWLEDGEMENT. Must match the agent’s approved use case.

​
Responses

{
  "message_id": "msg_car_c3d4e5",
  "status": "queued",
  "created_at": "2026-03-28T09:00:00Z",
  "billing": {
    "channel": "RCS",
    "message_type": "single_message",
    "hold_amount": 0.12,
    "message_price": 0.10,
    "balance": { "free": 49.88, "reserved": 0.12, "total": 50.00 },
    "tier": { "channel": "RCS", "current": "tier_1", "volume_used": 1252 }
  }
}
​
billing.message_type
string
Always single_message for carousel content.
​
billing.hold_amount
number
Balance held until delivery resolves.
​
billing.message_price
number
Expected unit price for this classification and tier.