API REFERENCE

Messaging API reference

Endpoints for sending category-tagged messages and follower-scoped Service messages with a developer-app token.

Base URL and authentication

Download the canonical OpenAPI 3.1 contract for tooling and code generation.

Create a developer app in the Business console and send its one-time API token as Authorization: Bearer <APP_TOKEN>. Tokens start with cxa_, are tied to one business account, and must have the scope required by the endpoint. Keep them on your server and rotate or revoke them from the console if exposed.

Send a unique Idempotency-Key header with each logical message. A retry with the same key and content returns the original operation ID without sending again. Reusing a key for different content returns idempotency_key_conflict.

Responses share one envelope: { "success": true, "message": "message_sent", "data": { "id": "...", "status": "sent" }, "timestamp": "..." } on success, or { "success": false, "message": "<error_code>", "data": null, "timestamp": "..." } on failure.

Send a message

POST/v1/:businessAccountId/messagesSend a marketing, authentication, or utility message. Requires a live workspace and a developer app scoped to the chosen category.

:businessAccountId is the UUID of the business account that owns the developer app. A token issued to another account is rejected.

Request parameters

Field	Type	Description
to	String	Required. The recipient's phone number, including country code.
category	String	Required. One of `marketing`, `authentication`, `utility`. The app token must have the matching scope.
body	String	Plain message text. Required for `utility`; optional for `marketing`. Mutually exclusive with `message_content`.
message_content	Object	Structured content. Required for `authentication`; optional for `marketing`. Mutually exclusive with `body`.

Sending both body and message_content, or neither where one is required, is rejected with invalid_message_content. See Authentication, Utility, and Marketing for the exact shape each category accepts.

Example response

{
  "success": true,
  "message": "message_sent",
  "data": {
    "id": "b1a2c3d4-1111-2222-3333-44444444e5f6",
    "status": "sent"
  },
  "timestamp": "2026-09-28T10:30:00Z"
}

This response confirms the send request was accepted. The final outcome arrives asynchronously as a message.sent or message.failed webhook.

Send a Service message

POST/v1/service/:phoneNumber/messagesSend free-form text to a customer who actively follows the business. Requires the service scope.

:phoneNumber is the business's own ChatX phone number, not the recipient number or an account ID.

{
  "to": "+15559876543",
  "body": "Thanks for reaching out - here is the update you asked about."
}

Rate-limited to one message per recipient per minute, separately from category sends. See Service for follower requirements and behavior.

Common errors

invalid_app_token

The developer-app token is invalid, expired, revoked, or belongs to a different business account.

app_scope_required

The token lacks the message category scope or the service scope required by the request.

not_a_business_account

The caller does not own a business account.

live_business_required

The business account is still in sandbox mode and has not been promoted to live customer messaging.

invalid_message_category

category is missing or is not one of marketing, authentication, utility.

message_body_required

A plain-text category was sent with an empty or missing body.

invalid_message_content

The category requires a different combination of body and message_content, or message_content does not match the shape that category accepts.

invalid_phone_number

A business or recipient phone number is not valid.

recipient_not_found

No ChatX user has the supplied recipient phone number.

business_not_found

The business phone number in the Service URL does not resolve to an account.

business_follow_required

The recipient does not actively follow the business. Authentication category messages are exempt.

marketing_opt_in_required

The follower has not opted in to marketing messages.

business_send_rate_limited

The business already sent to this recipient within the route's one-minute window.

invalid_idempotency_key

The key is longer than 255 characters or has leading or trailing whitespace.

idempotency_key_conflict

The same caller already used this key for different request content.

idempotency_in_progress

An identical request with this key is still being processed. Retry it later with the same key.