External API

Send events from your systems into the inbox

One HTTP request drops a text message into its own thread, next to WhatsApp chats. It is not sent on WhatsApp, and it does not mix into a customer conversation.

Start free trialSee pricing

After you sign in, create a token in Settings. The secret is shown once.

What the API does

Ingest, not outbound

POST a text message into a WhatsApp session you already connected. Chato stores it and shows it live in the dashboard. It does not send a WhatsApp message, and there is no reply channel back to your system.

One thread per source

sourceId shopify always lands in the same chat, ext:shopify@external. A second source, such as website, is a different thread on that same session.

Kept out of customer chats

The thread is labeled External and the composer is view-only. Order alerts and form submissions stay beside the inbox instead of inside a customer history.

Where teams use it

Anything that should sit next to WhatsApp, without becoming a WhatsApp message.

Orders and payments

New order, paid, refunded. The session for that shop shows a Shopify thread instead of a fake customer chat.

Website forms

A contact or booking form posts the submission. Staff read it in the same dashboard as WhatsApp.

CRM and helpdesk

Deal changes, ticket escalations, or assignment notes. Give each tool its own source id so the threads stay separate.

Internal tools

Inventory, monitoring, or an ops script. One account token can post into any session that belongs to that account.

How to send the first message

  1. 01

    Create a token

    Open Settings, then External API. Name it after the integration, for example Shopify. Copy the secret immediately. Chato stores only a hash, and the full token is not shown again. Revoke it there when you rotate or stop an integration.

  2. 02

    Copy the session id

    In the dashboard, open the menu for the WhatsApp number that should receive the thread and choose Copy session ID. That session must belong to the same account as the token.

  3. 03

    POST the message

    Send JSON to POST /api/external/messages with Authorization: Bearer and your token. sourceId chooses the thread. externalMessageId lets you retry without creating a duplicate.

  4. 04

    Open the thread

    The source appears in that session’s chat list under the source name. Sending the same externalMessageId again returns the original message and does not add a second bubble.

Endpoints

Message calls use the API token. Creating, listing, and revoking tokens uses your signed-in Chato session, the same way Settings does.

MethodPathAuthWhat it does
POST/api/external/messagesAPI tokenStore a text message on a session. 201 when it is new, 200 when that externalMessageId already exists.
GET/api/external/meAPI tokenCheck that the token is valid. Returns authenticated and the account id. It does not list sessions.
GET/api/external/tokensSigned-in sessionList active tokens: name, prefix, created time, last used. Secrets are not included.
POST/api/external/tokensSigned-in sessionCreate a token. Body is { "name": "Shopify" }. The secret is in the response once.
DELETE/api/external/tokens?id=TOKEN_IDSigned-in sessionRevoke a token. Later calls with that secret return 401.

Base URL: https://chato.pro. Use the host you sign in to if you are not on chato.pro.

Message fields

JSON body for POST /api/external/messages.

FieldRequiredWhat it does
sessionIdRequiredThe WhatsApp session that should show the thread. Copy it from the dashboard. 404 if it is not on this account.
sourceIdRequiredThread key. 2–64 characters: letters, numbers, hyphens, underscores. Spaces become hyphens and the value is lowercased. The chat id is ext:<sourceId>@external.
messageRequiredThe text shown in the thread. It must be non-empty and at most 4096 characters.
sourceNameOptionalDisplay name, such as Shopify Orders. If omitted, the source id is title-cased.
externalMessageIdOptionalYour id for this event. Sending it again for the same session and source returns the original message and does not emit another live update.
metadataOptionalExtra JSON object stored with the message. It is not shown as the chat text.

Example request

Replace YOUR_TOKEN and the session id. A new message responds with created: true and chat id ext:shopify@external.

Example response

created is false, with HTTP 200, when externalMessageId was already stored.

curl -X POST https://chato.pro/api/external/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "your-session-id",
    "sourceId": "shopify",
    "sourceName": "Shopify Orders",
    "message": "New order #1234",
    "externalMessageId": "order-1234"
  }'
{
  "success": true,
  "created": true,
  "messageId": "ext_shopify_order-1234",
  "chatId": "ext:shopify@external",
  "sourceId": "shopify",
  "timestamp": 1710000000
}

Authentication

Send the token on every message call. Prefer the Authorization header so the secret is not written into a URL or a proxy log.

  • Authorization: Bearer <token>
  • X-Api-Key: <token>
  • ?key=<token>

A token is an account credential. Any active token can post into any session on that account. Revoking it in Settings stops it immediately. Each successful call updates last used. The secret looks like chato_ followed by 48 hex characters. Settings later shows only the start of the token.

After a successful call

  • The message is stored with source external. WhatsApp is not contacted.
  • An open dashboard for that session receives the new message live.
  • The thread id is ext:<sourceId>@external.
  • Repeating externalMessageId returns HTTP 200 and created: false.
  • Unread state is local to Chato. Opening the thread does not send a WhatsApp read receipt.
  • Deleting an external message removes it from Chato only.

What it will not do

  • It does not send WhatsApp messages, media, or templates.
  • You cannot reply from the thread back to the external system.
  • It is not the Meta Cloud API or the official WhatsApp Business API.
  • It accepts text only. There is no media upload on this endpoint.
  • A token cannot write into another account’s sessions.
  • Chato does not call your server when someone reads the thread.

Responses

  • 201 — Message stored.
  • 200 — That externalMessageId already existed. The existing message is returned.
  • 400 — Missing sessionId, invalid sourceId, or an empty or oversized message.
  • 401 — Missing, unknown, or revoked token.
  • 404 — sessionId is not on this account.
  • 405 — Wrong HTTP method.

Generate a token, point one system at a session, and keep those events in their own thread.

Start free trial