Send message
Sends an RCS message to a recipient. Two modes, selected with the type field: template-based (type: TEMPLATE, the default — combining a template_id and an agent_id of the account) and free-form (type: TEXT | FILE | RICH_CARD | CAROUSEL, with the content directly in the body and no template). The send is asynchronous in both modes: the API responds 202 Accepted immediately with a message_id; the actual result (delivered / read / failed) and the user’s interactions arrive later through webhooks, correlated by that message_id.
Validation rules (both modes):
tomust be exactly 10 digits, without the country code (the system prepends52).- Variables: the
{{placeholders}}— of the template, or written in the free-form content — are substituted withvariables, all of them must be provided (RCS_MISSING_VARIABLESotherwise), variables of type URL (those placed infileUrl/thumbnailUrl/iconUrl/url) must be validhttp/httpsURLs (RCS_INVALID_VARIABLE_FORMATotherwise), andUUID_MESSAGEis a reserved name rejected with400— it is resolved internally by the system. - Referenced media (images/video) is validated with a real HEAD request: MIME type and size must comply with the RCS specifications (
RCS_INVALID_MEDIA_FILEotherwise).
Template mode only:
- The agent and the template must belong to the account and be of the same type (
RCS_TYPE_MISMATCHotherwise).
Free-form mode only:
template_idis forbidden (and vice versa: it is required inTEMPLATEmode).- One content per request → 1 credit.
- Content is validated against the agent’s type instead of
RCS_TYPE_MISMATCH: aBASICagent only supportstype: TEXTand nosuggestions(RCS Basic has no buttons) —RCS_CONTENT_TYPE_NOT_ALLOWED_FOR_AGENT(376) /RCS_SUGGESTIONS_NOT_ALLOWED(377) otherwise;SINGLEandCONVERSATIONALagents support the four content types and suggestions. - Root-level
suggestions(message-level chips, max 11) are independent from thesuggestionsembedded inside a card: they can be combined. Never sendpostbackDatain a suggestion — the backend generates it.
Authentication
Account authentication key. The App-Key must have the RCS channel enabled.
OAuth 2.0 access token issued by POST /api/oauth/token (client-credentials). Takes precedence over x-api-key when both are sent. See the Authentication section.
Request
Destination number: exactly 10 digits, WITHOUT the country code (the system automatically prepends 52).
Agent identifier. It must be enabled (status: true). In template mode it must be of the SAME type as the template; in free-form mode the content is validated against the agent’s type (a BASIC agent only supports TEXT without suggestions) and the billing channel (RCS_BASIC / RCS_SINGLE / RCS_CONVERSATIONAL) is derived from it.
Sending mode. TEMPLATE (the default when omitted) sends by template; the other four are free-form sends with the content directly in the body: TEXT (text), FILE (contentInfo), RICH_CARD (richCard.standaloneCard), CAROUSEL (richCard.carouselCard).
Template identifier. Required with type: TEMPLATE (it must exist, be active, and belong to the account of the App-Key); forbidden (400) with any free-form type.
Free-form TEXT content. Required with type: TEXT, forbidden with any other type. Supports {{placeholders}} substituted with variables.
Free-form FILE content. Required with type: FILE, forbidden with any other type.
Free-form card content. With type: RICH_CARD it must carry standaloneCard (and carouselCard is forbidden); with type: CAROUSEL it must carry carouselCard (2 to 10 cards, and standaloneCard is forbidden). Forbidden with any other type.
Message-level chips, only for the four free-form types (forbidden with type: TEMPLATE; also rejected with a BASIC agent — errorCode 377). Maximum 11. Independent from the suggestions embedded inside a card: they can be combined. Never send postbackData: the backend generates it.
Map { variable_name: value }. In template mode, ALL the variables declared by the template must be sent; in free-form mode it substitutes the {{placeholders}} written in the body content, with the same type rules (URL in fileUrl/thumbnailUrl/iconUrl/url, free text elsewhere) and the same HEAD media validation. If any is missing, the request is rejected with RCS_MISSING_VARIABLES (errorCode 344). UUID_MESSAGE is a reserved name, rejected with 400 in every mode.
Optional, in minutes. Time during which delivery of the message is attempted before it expires. Default: provider default (~24 h). Maximum: 1440 (24 h).
Optional, in minutes. Window during which user interactions (clicks/replies) on this message are accepted. Default: 1440 (24 h). Maximum: 4320 (72 h). After the window, inbound events are discarded and NOT notified through webhooks.
Optional SMS fallback for this send: if the RCS message is not delivered (its delivery status webhook reports FAILED or EXPIRED), the API automatically retries the same recipient over SMS with this content. A late FAILED/EXPIRED that the RCS status priority logic already discards (a suppressed downgrade, an out-of-order event) does NOT fire the fallback — only a failure that actually advances the message status does. It fires only once per message and it is a single hop (RCS → SMS, no further cascade). Requires the multichannel fallback to be enabled for the account (errorCode 380/381 otherwise). Applies the same in both sending modes.
Response
Message accepted for delivery. Store message_id: it is the key to correlate every webhook of this send.
Send identifier. Store it: it is the key to correlate every webhook of this send.