Sending RCS Messages via API

Send individual RCS messages programmatically, with full control over message type, suggestions, and fallback behaviour.

📘
You only need an Agent to send RCS directly through the API — a Sender Service is not required unless you want automatic SMS fallback. See RCS Agents.

Send a message

POST /rcs/agents/{agentId}/messages/send

Full request and response reference: Send RCS message

Parameter	Description
`agentId`	The Agent to send from (path parameter)
`to`	Recipient number in E.164 format, without the leading `+`
`message`	The message content — see Supported RCS message types for `text`, `standaloneRichCard`, `carouselRichCard`, and `file`
`suggestions`	Optional suggested replies or actions, see below
`expireAfter`	Optional. Stop attempting delivery after this many minutes
`revoke`	Optional. If `true`, revoke the message once it expires without being delivered
`fallback`	Optional. Automatic SMS fallback, see below

Suggestions

Suggestions are tappable buttons displayed with your message. You can add them in two places:

Placement	Where to set it	Maximum
Below the message (chips)	`suggestions` at the root of the request	11
Inside a rich card or carousel card (buttons)	`suggestions` inside `cardContent`	4 per card

Suggested reply — sends a predefined reply back to your Agent when tapped.

Field	Description
`type`	`reply`
`text`	Visible text of the button, max 25 characters
`postbackData`	Data your Agent receives when the reply is tapped, max 2,048 characters

Suggested action — triggers an action on the recipient's device when tapped.

Field	Description
`type`	`action`
`text`	Visible text of the button, max 25 characters
`postbackData`	Data your Agent receives when the action is tapped, max 2,048 characters
`action`	One of the action types below

Action	Description
`openUrlAction`	Opens a URL in the recipient's browser, or inside the messaging app with `application: WEBVIEW`
`dialAction`	Opens the recipient's dialer with a phone number pre-filled
`viewLocationAction`	Opens the recipient's default map app at a given latitude/longitude, with an optional label
`shareLocationAction`	Asks the recipient to pick a location and send it back to your Agent
`createCalendarEventAction`	Opens the recipient's calendar app with a new event pre-filled (start time, end time, title, description)

For every field, limit and example, see Supported RCS message types.

Message traffic type

Every message carries a messageTrafficType, which tells the carrier what kind of message it is:

Value	Use for
`AUTHENTICATION`	One-time passcodes and login verification
`TRANSACTION`	Order confirmations, delivery updates, and similar
`PROMOTION`	Marketing and promotional content (default)
`SERVICEREQUEST`	Customer service replies
`ACKNOWLEDGEMENT`	Confirmation that a previous message or action was received

Automatic SMS fallback

To fall back to SMS when RCS delivery isn't possible, include a fallback object with a senderServiceId and the SMS body to send instead, plus an optional type for SMS encoding (text, unicode, or auto, default text). See RCS to SMS Fallback for how fallback is triggered and how the Sender Service is used.

Typing and read events

You can send typing indicators or read receipts to a recipient from your Agent:

POST /rcs/agents/{agentId}/events

Full request and response reference: Send RCS events

This lets the recipient see your Agent is "typing…" or has read their message, the same way they would in a conversation with a contact.

Revoking a message

If a message was sent by mistake or is no longer relevant, you can revoke it before it's read:

DELETE /rcs/agents/{agentId}/messages/{messageId}

What's next

Testing RCS Messages — validate on real devices before launch
RCS Broadcasts — send these message types in bulk
RCS to SMS Fallback
RCS Status & Error Codes — track delivery of what you send