Send message | Chat Bridge

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):

to must be exactly 10 digits, without the country code (the system prepends 52).
Variables: the {{placeholders}} — of the template, or written in the free-form content — are substituted with variables, all of them must be provided (RCS_MISSING_VARIABLES otherwise), variables of type URL (those placed in fileUrl/thumbnailUrl/iconUrl/url) must be valid http/https URLs (RCS_INVALID_VARIABLE_FORMAT otherwise), and UUID_MESSAGE is a reserved name rejected with 400 — 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_FILE otherwise).

Template mode only:

The agent and the template must belong to the account and be of the same type (RCS_TYPE_MISMATCH otherwise).

Free-form mode only:

template_id is forbidden (and vice versa: it is required in TEMPLATE mode).
One content per request → 1 credit.
Content is validated against the agent’s type instead of RCS_TYPE_MISMATCH: a BASIC agent only supports type: TEXT and no suggestions (RCS Basic has no buttons) — RCS_CONTENT_TYPE_NOT_ALLOWED_FOR_AGENT (376) / RCS_SUGGESTIONS_NOT_ALLOWED (377) otherwise; SINGLE and CONVERSATIONAL agents support the four content types and suggestions.
Root-level suggestions (message-level chips, max 11) are independent from the suggestions embedded inside a card: they can be combined. Never send postbackData in a suggestion — the backend generates it.

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): - `to` must be exactly 10 digits, without the country code (the system prepends `52`). - Variables: the `{{placeholders}}` — of the template, or written in the free-form content — are substituted with `variables`, all of them must be provided (`RCS_MISSING_VARIABLES` otherwise), variables of type URL (those placed in `fileUrl`/`thumbnailUrl`/`iconUrl`/`url`) must be valid `http`/`https` URLs (`RCS_INVALID_VARIABLE_FORMAT` otherwise), and `UUID_MESSAGE` is a **reserved name** rejected with `400` — 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_FILE` otherwise). Template mode only: - The agent and the template must belong to the account and be of the **same type** (`RCS_TYPE_MISMATCH` otherwise). Free-form mode only: - `template_id` is **forbidden** (and vice versa: it is required in `TEMPLATE` mode). - One content per request → 1 credit. - Content is validated against the **agent's type** instead of `RCS_TYPE_MISMATCH`: a `BASIC` agent only supports `type: TEXT` and no `suggestions` (RCS Basic has no buttons) — `RCS_CONTENT_TYPE_NOT_ALLOWED_FOR_AGENT` (376) / `RCS_SUGGESTIONS_NOT_ALLOWED` (377) otherwise; `SINGLE` and `CONVERSATIONAL` agents support the four content types and suggestions. - Root-level `suggestions` (message-level chips, max 11) are independent from the `suggestions` embedded inside a card: they can be combined. Never send `postbackData` in a suggestion — the backend generates it.

Authentication

x-api-keystring

Account authentication key. The App-Key must have the RCS channel enabled.

Request

This endpoint expects an object.

tostringRequiredformat: "^\d{10}$"

Destination number: exactly 10 digits, WITHOUT the country code (the system automatically prepends 52).

agent_idstringRequired

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.

typeenumOptionalDefaults to TEMPLATE

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_idstringOptional

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.

textstringOptional>=1 character

Free-form TEXT content. Required with type: TEXT, forbidden with any other type. Supports {{placeholders}} substituted with variables.

contentInfoobjectOptional

Free-form FILE content. Required with type: FILE, forbidden with any other type.

richCardobjectOptional

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.

suggestionslist of objectsOptional

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.

variablesmap from strings to stringsOptional

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.

ttl_messageintegerOptional1-1440

Optional, in minutes. Time during which delivery of the message is attempted before it expires. Default: provider default (~24 h). Maximum: 1440 (24 h).

ttl_eventsintegerOptional1-4320

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.

fallbackobjectOptional

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.

message_idstringOptionalformat: "uuid"

Send identifier. Store it: it is the key to correlate every webhook of this send.

status"ACCEPTED"Optional

Initial status of the send.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

$	curl -X POST https://connect.chatbridge.mx/v1/rcs/messages \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"to": "5512345678",
>	"agent_id": "665f1a2b3c4d5e6f7a8b9c9a",
>	"template_id": "665f1a2b3c4d5e6f7a8b9c0d",
>	"variables": {
>	"nombre": "Iván"
>	}
>	}'