POST /v1/messages with message_type: MESSAGE and a text body. Classification into Basic or Single depends on content:
ConditionBilling unit
Text ≤ 160 UTF-8 chars, no suggestions, no rich bodyBasic Message
Text > 160 chars, or any suggestions, or rich contentSingle Message
traffic_type (for example TRANSACTION, PROMOTION) is required and must reflect the regulatory classification of your use case.

​
Request

​
Path params / headers

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

​
Body — Basic text (no suggestions)

{
  "to": "+4917612345678",
  "agent_id": "ag_live_xxxx",
  "message_type": "MESSAGE",
  "content": {
    "text": "Your order has shipped."
  },
  "traffic_type": "TRANSACTION",
  "ttl": "3600s"
}
​
to
string
required
Destination phone number in international format (e.g. +4917612345678).
​
agent_id
string
required
Approved production agent id (ag_live_…). Must be in APPROVED state.
​
message_type
string
required
MESSAGE for one-shot sends.
​
content.text
string
required
Message body in UTF-8. Maximum 3,072 characters. Keep ≤ 160 characters with no suggestions to stay on Basic pricing.
​
traffic_type
string
required
Regulatory classification of the message content. Must match the agent’s approved use_case.
ValueUse when
AUTHENTICATIONOne-time passwords and authentication codes (OTP agents)
TRANSACTIONTransactional alerts related to an existing customer relationship
PROMOTIONMarketing and promotional content
SERVICEREQUESTService messages the user has explicitly consented to receive
ACKNOWLEDGEMENTConfirming receipt of a user’s unsubscribe or opt-out request
​
ttl
string
Delivery expiry as a duration string (for example "3600s"). Message is automatically revoked if not delivered within this window.

​
Body — Text with suggestions (Single Message)

Any suggestions array forces Single Message classification, regardless of text length: 
{
  "to": "+4917612345678",
  "agent_id": "ag_live_xxxx",
  "message_type": "MESSAGE",
  "content": {
    "text": "Your order #1234 has shipped!",
    "suggestions": [
      { "reply": { "text": "Track order", "postback_data": "track_1234" } },
      { "action": { "text": "Call support", "dial": { "phone_number": "+4930123456" } } }
    ]
  },
  "traffic_type": "TRANSACTION",
  "ttl": "3600s"
}
​
content.suggestions
array
Array of suggestion chips. Maximum 11 suggestions per message. Any non-empty suggestions array triggers Single Message billing.Each item is one of:
  • reply — quick reply chip: { "text": "...", "postback_data": "..." }. Text max 25 chars. postback_data must be base64-encoded; max 2048 chars.
  • action — native action chip: { "text": "...", "fallback_url": "...", "<action_type>": { ... } }. Text max 25 chars. fallback_url is optional; opens in browser on devices that don’t support the native action.
Action typeRequired fieldsNotes
dialphone_numberInternational format (e.g. +4930123456)
open_urlurlhttps:// or http:// only — tel:, mailto:, and sms: schemes rejected since Nov 2025
open_url_in_webviewurl, view_mode (FULL, HALF, TALL)Requires device support for ACTION_OPEN_URL_IN_WEBVIEW
view_locationlat + long + optional label; or query stringOpens map app
share_location(no fields)Lets user share their location back
create_calendar_eventtitle (max 100 chars), description (max 500 chars), start_time, end_timeOpens calendar pre-filled

​
Responses

Message accepted; dispatch is async. Poll GET /v1/messages/{id} or listen for message.* webhooks.
{
  "message_id": "msg_a1b2c3d4",
  "status": "queued",
  "created_at": "2026-03-28T09:00:00Z",
  "billing": {
    "channel": "RCS",
    "message_type": "basic_message",
    "hold_amount": 0.12,
    "message_price": 0.08,
    "balance": {
      "free": 49.88,
      "reserved": 0.12,
      "total": 50.00
    },
    "tier": {
      "channel": "RCS",
      "current": "tier_1",
      "volume_used": 1250
    }
  }
}
​
message_id
string
Unique message id. Use with GET /v1/messages/{id}, DELETE, and for webhook correlation.
​
status
string
Initial state — always queued on accept. Final state arrives via webhook or GET.
​
created_at
string
ISO 8601 UTC timestamp when the send was accepted.
​
billing
object
Cost snapshot for this send.