RCS Business Messaging

RCS Business Messaging lets your agent text as a branded sender — your name and logo on the thread instead of a bare phone number — with delivery and read receipts, and tappable quick-reply chips. It runs through the same POST /v1/messages endpoint as every other channel.

Your RCS line

An RCS agent arrives on your account as a line whose address starts with rcs_ (for example rcs_acme) instead of a phone number. It behaves like any other number: attach it to an agent, see its threads in Conversations, receive inbound through the same webhooks.

Sending

RCS fields and the rcs channel override are intentionally omitted from the public OpenAPI schema and generated SDK types while onboarding is concierge-only. The HTTP request below is supported for enabled accounts; use it instead of expecting these fields in the generated SDK.

Address RCS explicitly — use your rcs_ address as from_number, or pass channel: "rcs":

curl -X POST https://api.agentphone.ai/v1/messages \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "rcs_acme",
    "to_number": "+13105550123",
    "channel": "rcs",
    "body": "Your order has shipped! Want delivery updates?",
    "buttons": ["Yes, keep me posted", "No thanks"]
  }'

To select your branded RCS line reliably, specify it explicitly. Automatic selection by agent_id depends on eligible attached numbers and their capabilities; it is not a promise to use SMS or your branded RCS identity.

buttons become tappable quick-reply chips (up to 11 per message, 25 characters each). A tap comes back as a normal inbound message carrying the chip’s text.

Rich cards

For an image with text, send a card with an empty body. Do not also pass media_urls, a carousel, or top-level buttons. The card accepts a title (up to 200 characters), description (up to 2,000), and a public HTTPS media_url; at least one of those content fields must be present.

curl --fail-with-body "https://api.agentphone.ai/v1/messages" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "rcs_acme",
    "to_number": "+14155550123",
    "channel": "rcs",
    "body": "",
    "card": {
      "title": "Your order is ready",
      "description": "Collect it at the front desk.",
      "media_url": "https://example.com/order.jpg",
      "media_height": "MEDIUM",
      "orientation": "VERTICAL"
    },
    "fallback_text": "Your order is ready. Collect it at the front desk."
  }'

Replace the sample image URL with your own reachable asset. media_height can be SHORT, MEDIUM, or TALL and requires media_url; orientation can be VERTICAL or HORIZONTAL. The example’s fallback_text requires an SMS fallback line configured during onboarding.

SMS fallback

Not every handset can receive RCS. If your line has an SMS fallback number configured (we set this up with you during onboarding), a send to a non-RCS handset is delivered automatically as a plain text from that number — same API call, nothing to detect on your side.

The message’s channel always reflects what you asked for (rcs); when delivery actually happened over SMS, the message carries deliveredChannel: "sms" so downgrades are never invisible. In the dashboard those messages show “Delivered as SMS”.

The fallback number is a real number on your account: replies to it reach the same agent, and it can’t be released while it’s serving as a fallback.

Opt-outs — what you must send yourself

When a recipient replies STOP (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT), AgentPhone records the opt-out and blocks further sends to them from your RCS agent — subsequent sends return a clear 403. A reply of START opts them back in.

AgentPhone never sends messages on your behalf, so your agent or backend must send the opt-out confirmation text itself (the STOP response you provided during carrier onboarding). The same applies to HELP responses. One confirmation message is allowed after a STOP; anything further is blocked until the recipient opts back in.

Billing

RCS text is billed per 160-byte UTF-8 segment; rich media is billed per message, inbound and outbound. Standard rates are $0.013/text segment and $0.031/rich-media message, with account-specific overrides possible. Check Billing (the RCS tab in transaction history). A message that falls back to SMS bills at the rate of the send you requested.