Developer Guides

Send Messages via API

Send messages to your contacts on any channel — WhatsApp Official, WhatsApp Unofficial, Instagram, Facebook, Telegram, and Webchat — through one channel-agnostic endpoint:

Code
POST https://api.chatmo.io/v1/open-api/messages

You supply a channel (which number/inbox to send from) and a recipient — ChatMo resolves or creates the conversation for you, so you never have to manage conversation IDs.

:::info Authentication Every request needs your API key in the x-api-key header (or a Bearer JWT). API keys are available on the Professional plan and above — create one in the dashboard under Settings → Developers → API Keys. :::

Quick start

Code
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_a3f2b1_QwErTyUiOp..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "92b56f11-5bc2-499f-9275-bc55a352f2d0",
    "to": { "phone": "628123456789" },
    "type": "TEXT",
    "text": "Hello from the ChatMo API 👋"
  }'

A successful call returns 200 with the created message:


Code
{
  "success": true,
  "code": 200,
  "message": "message sent",
  "data": {
    "message_id": "c2d3e4f5-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
    "conversation_id": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "status": "SENT",
    "external_message_id": "wamid.HBgMNjI4MTIz...",
    "type": "TEXT",
    "channel": { "id": "92b56f11-...", "name": "Acme Store", "type": "WHATSAPP_OFFICIAL" },
    "contact": { "id": "a1b2c3d4-...", "name": "Sarah Wijaya", "identifier": "628123456789" },
    "sent_at": "2026-07-03T10:15:30Z"
  }
}

Step 1 — Get your `channel_id`

channel_id tells ChatMo which of your connected numbers/accounts to send from (one organization can have many). You have two ways to find it.

Option A — Look it up by a memorable identifier

Use GET /channels/by-identifier with something you already know — a phone number, an @username, a Page name, or a widget id:

Code
curl "https://api.chatmo.io/v1/open-api/channels/by-identifier?identifier=628123456789" \
  -H "x-api-key: chatmo_live_..."


Code
{
  "success": true,
  "code": 200,
  "message": "success",
  "data": {
    "id": "92b56f11-5bc2-499f-9275-bc55a352f2d0",
    "name": "Acme Store",
    "type": "WHATSAPP_OFFICIAL",
    "status": "ACTIVE",
    "identifier": "628123456789",
    "phone_number": "628123456789"
  }
}

Which identifier matches depends on the channel type:

Channel	Identifier to pass
WHATSAPP_OFFICIAL	phone number, e.g. `628123456789`
WHATSAPP_UNOFFICIAL	device phone number
INSTAGRAM	`@username`
FACEBOOK	Page name
TELEGRAM	bot `@username` or numeric bot id
WEBCHAT	widget id

Phone numbers are matched digit-normalized, so +62…, 62…, and spaced/dashed variants all resolve. Add &type=WHATSAPP_OFFICIAL to disambiguate when the same identifier could match more than one channel.

Option B — List all your channels

GET /inboxes returns a paginated list of your channels (id, name, type, status) — handy for building a dropdown.

Code
curl "https://api.chatmo.io/v1/open-api/inboxes?limit=50" -H "x-api-key: chatmo_live_..."

Step 2 — Address the recipient

Provide a to object alongside channel_id. For WhatsApp, pass the full international phone number with the country code included and no leading 0 (e.g. 628123456789) — don't send a separate country code.


Code
"to": { "phone": "628123456789", "name": "Sarah Wijaya" }

name is optional and used only when the contact is brand new.

What to put in to, per channel:

Channel	`to`
WhatsApp Official / Unofficial	`{ "phone": "628123456789" }`
Instagram	`{ "type": "external_id", "value": "<Instagram-scoped user id>" }`
Facebook	`{ "type": "external_id", "value": "<Page-scoped PSID>" }`
Telegram	`{ "type": "external_id", "value": "<Telegram user id>" }`
Webchat	reply via `conversation_id` (webchat visitors have no dialable address)

For Instagram / Facebook / Telegram, to.value is the platform-scoped user id captured on inbound webhooks — it's stored as the contact's external_id.

:::tip Easiest path — reply in an existing thread On any channel you can skip to and pass conversation_id to reply inside a known conversation:


Code
{ "channel_id": "92b56f11-...", "conversation_id": "3f9a1b2c-...", "type": "TEXT", "text": "Thanks!" }

:::

Per-channel examples:

Code
# Instagram — TEXT
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<ig_channel_id>","to":{"type":"external_id","value":"17841400000000000"},"type":"TEXT","text":"Thanks for reaching out on Instagram!"}'

# Facebook Messenger — TEXT
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<fb_channel_id>","to":{"type":"external_id","value":"6123456789012345"},"type":"TEXT","text":"Hi! Thanks for messaging our Page."}'

# Telegram — TEXT
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<tg_channel_id>","to":{"type":"external_id","value":"987654321"},"type":"TEXT","text":"Hello from our Telegram bot!"}'

# Webchat — reply in an existing conversation
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<webchat_channel_id>","conversation_id":"<conversation_id>","type":"TEXT","text":"An agent will be with you shortly."}'

Message types

type selects the message kind. Support varies by channel:

Type	WA Official	WA Unofficial	Instagram	Facebook	Telegram	Webchat
TEXT	Yes	Yes	Yes	Yes	Yes	Yes
IMAGE / VIDEO / DOCUMENT / AUDIO / FILE	Yes	Yes	Yes	Yes	Yes	Yes
TEMPLATE	Yes	—	—	—	—	—
INTERACTIVE	Yes (native, ≤3)	As numbered text	Yes (native, ≤13)	—	—	—

A dash (—) means the type is not supported on that channel — sending it returns 400 UNSUPPORTED_MESSAGE_TYPE. FILE is an alias for DOCUMENT.

Text


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "TEXT",
  "text": "Hi Sarah! Your order has been processed 🙌"
}

Image / Video / Audio / Document

Media accepts either a file_id (uploaded via POST /uploads, see below) or a public url:


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "IMAGE",
  "media": { "url": "https://cdn.example.com/promo.jpg", "caption": "New promo!" }
}


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "DOCUMENT",
  "media": { "file_id": "b7c1a0d2-9f3e-4c5a-8b2d-1e2f3a4b5c6d", "filename": "invoice-12345.pdf" }
}

The media's real type must match type — e.g. sending a .pdf as IMAGE is rejected with 400 VALIDATION_ERROR. DOCUMENT accepts any file.

Template (WhatsApp Official only)

Templates are the only way to start a WhatsApp conversation outside the 24-hour customer-service window. The approved template is re-resolved server-side by (name + language + channel); you only supply the variable values.


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "TEMPLATE",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": { "1": "Sarah", "2": "12345" },
    "media_url": "https://cdn.example.com/header.jpg"
  }
}

variables are keyed "1", "2", … matching the {{1}}, {{2}} placeholders in the template body.
media_url is only needed when the template's header is an image/video/document.
Find your approved templates (name, language, variables) via GET /whatsapp-templates.

:::tip Finding templates

Code
curl "https://api.chatmo.io/v1/open-api/whatsapp-templates?channel_id=92b56f11-...&status=APPROVED" \
  -H "x-api-key: chatmo_live_..."

:::

Interactive (reply buttons)

Native reply buttons on WhatsApp Official (max 3) and Instagram (max 13). On WhatsApp Unofficial they degrade to a numbered-text list; other channels return 400.


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "INTERACTIVE",
  "interactive": {
    "body": "Did your order arrive?",
    "buttons": [
      { "id": "yes", "title": "Yes" },
      { "id": "no", "title": "No" }
    ]
  }
}

The id is the payload echoed back to you when the customer taps the button.

Uploading media

To send media by file_id, upload the file first with POST /uploads (multipart):

Code
curl -X POST https://api.chatmo.io/v1/open-api/uploads \
  -H "x-api-key: chatmo_live_..." \
  -F "file=@/path/to/invoice.pdf"

The response returns an id — pass it as media.file_id. Alternatively, skip the upload entirely and send a public media.url.

Optional fields

Field	Description
`reply_to_message_id`	Native quoted reply — the internal message UUID or the channel-side external id of the parent message.
`client_reference`	Your own correlation id (≤128 chars). Echoed back in the response and stored on the message so you can reconcile later.

Error handling

Errors return a success: false envelope. The human-readable reason is in message; a stable machine code is in data.error_code — switch on that in your integration.


Code
{
  "success": false,
  "code": 400,
  "message": "TEMPLATE messages are only supported on WHATSAPP_OFFICIAL channels",
  "data": { "error_code": "UNSUPPORTED_MESSAGE_TYPE" }
}

HTTP	`error_code`	Meaning
400	`VALIDATION_ERROR`	Missing/invalid field, or media type mismatch.
400	`UNSUPPORTED_MESSAGE_TYPE`	The type isn't supported on that channel.
401	—	Missing or invalid API key.
402	`SUBSCRIPTION_EXPIRED`	Renew your subscription to keep using the API.
403	`FORBIDDEN`	Your key/role lacks permission.
404	`CHANNEL_NOT_FOUND`	Unknown channel or not in your organization.
404	`CONVERSATION_NOT_FOUND`	Unknown `conversation_id`.
404	`TEMPLATE_NOT_FOUND`	No approved template for that name/language/channel.
404	`MEDIA_NOT_FOUND`	`file_id` not found or not finished processing.
422	`CHANNEL_INACTIVE`	The channel isn't active.
502	`PROVIDER_ERROR`	The channel provider rejected the message (detail in `data.detail`). The message is still recorded as `FAILED`.
500	`INTERNAL_ERROR`	Unexpected server error — retry.

:::info Tracking sent messages Every call is logged in the dashboard under Settings → Developers → Send Message by API — with the request, response, HTTP status, latency, and delivery status. Messages sent through the API also show a "via API" badge in the chat inbox. :::

Endpoint	Purpose
`GET /channels/by-identifier`	Resolve a `channel_id` from a phone/username/page/widget id.
`GET /inboxes`	List all your channels.
`GET /whatsapp-templates`	List approved WhatsApp templates (name, language, variables).
`POST /uploads`	Upload media and get a `file_id`.
`GET /conversations/{conversation_id}/messages`	Read a conversation's message history.

Last modified on October 14, 2026

Developer Guides

Send Messages via API

Send messages to your contacts on any channel — WhatsApp Official, WhatsApp Unofficial, Instagram, Facebook, Telegram, and Webchat — through one channel-agnostic endpoint:

Code
POST https://api.chatmo.io/v1/open-api/messages

You supply a channel (which number/inbox to send from) and a recipient — ChatMo resolves or creates the conversation for you, so you never have to manage conversation IDs.

Quick start

Code
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_a3f2b1_QwErTyUiOp..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "92b56f11-5bc2-499f-9275-bc55a352f2d0",
    "to": { "phone": "628123456789" },
    "type": "TEXT",
    "text": "Hello from the ChatMo API 👋"
  }'

A successful call returns 200 with the created message:


Code
{
  "success": true,
  "code": 200,
  "message": "message sent",
  "data": {
    "message_id": "c2d3e4f5-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
    "conversation_id": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "status": "SENT",
    "external_message_id": "wamid.HBgMNjI4MTIz...",
    "type": "TEXT",
    "channel": { "id": "92b56f11-...", "name": "Acme Store", "type": "WHATSAPP_OFFICIAL" },
    "contact": { "id": "a1b2c3d4-...", "name": "Sarah Wijaya", "identifier": "628123456789" },
    "sent_at": "2026-07-03T10:15:30Z"
  }
}

Step 1 — Get your `channel_id`

channel_id tells ChatMo which of your connected numbers/accounts to send from (one organization can have many). You have two ways to find it.

Option A — Look it up by a memorable identifier

Use GET /channels/by-identifier with something you already know — a phone number, an @username, a Page name, or a widget id:

Code
curl "https://api.chatmo.io/v1/open-api/channels/by-identifier?identifier=628123456789" \
  -H "x-api-key: chatmo_live_..."


Code
{
  "success": true,
  "code": 200,
  "message": "success",
  "data": {
    "id": "92b56f11-5bc2-499f-9275-bc55a352f2d0",
    "name": "Acme Store",
    "type": "WHATSAPP_OFFICIAL",
    "status": "ACTIVE",
    "identifier": "628123456789",
    "phone_number": "628123456789"
  }
}

Which identifier matches depends on the channel type:

Channel	Identifier to pass
WHATSAPP_OFFICIAL	phone number, e.g. `628123456789`
WHATSAPP_UNOFFICIAL	device phone number
INSTAGRAM	`@username`
FACEBOOK	Page name
TELEGRAM	bot `@username` or numeric bot id
WEBCHAT	widget id

Option B — List all your channels

GET /inboxes returns a paginated list of your channels (id, name, type, status) — handy for building a dropdown.

Code
curl "https://api.chatmo.io/v1/open-api/inboxes?limit=50" -H "x-api-key: chatmo_live_..."

Step 2 — Address the recipient


Code
"to": { "phone": "628123456789", "name": "Sarah Wijaya" }

name is optional and used only when the contact is brand new.

What to put in to, per channel:

Channel	`to`
WhatsApp Official / Unofficial	`{ "phone": "628123456789" }`
Instagram	`{ "type": "external_id", "value": "<Instagram-scoped user id>" }`
Facebook	`{ "type": "external_id", "value": "<Page-scoped PSID>" }`
Telegram	`{ "type": "external_id", "value": "<Telegram user id>" }`
Webchat	reply via `conversation_id` (webchat visitors have no dialable address)

For Instagram / Facebook / Telegram, to.value is the platform-scoped user id captured on inbound webhooks — it's stored as the contact's external_id.

:::tip Easiest path — reply in an existing thread On any channel you can skip to and pass conversation_id to reply inside a known conversation:


Code
{ "channel_id": "92b56f11-...", "conversation_id": "3f9a1b2c-...", "type": "TEXT", "text": "Thanks!" }

:::

Per-channel examples:

Code
# Instagram — TEXT
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<ig_channel_id>","to":{"type":"external_id","value":"17841400000000000"},"type":"TEXT","text":"Thanks for reaching out on Instagram!"}'

# Facebook Messenger — TEXT
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<fb_channel_id>","to":{"type":"external_id","value":"6123456789012345"},"type":"TEXT","text":"Hi! Thanks for messaging our Page."}'

# Telegram — TEXT
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<tg_channel_id>","to":{"type":"external_id","value":"987654321"},"type":"TEXT","text":"Hello from our Telegram bot!"}'

# Webchat — reply in an existing conversation
curl -X POST https://api.chatmo.io/v1/open-api/messages \
  -H "x-api-key: chatmo_live_..." -H "Content-Type: application/json" \
  -d '{"channel_id":"<webchat_channel_id>","conversation_id":"<conversation_id>","type":"TEXT","text":"An agent will be with you shortly."}'

Message types

type selects the message kind. Support varies by channel:

Type	WA Official	WA Unofficial	Instagram	Facebook	Telegram	Webchat
TEXT	Yes	Yes	Yes	Yes	Yes	Yes
IMAGE / VIDEO / DOCUMENT / AUDIO / FILE	Yes	Yes	Yes	Yes	Yes	Yes
TEMPLATE	Yes	—	—	—	—	—
INTERACTIVE	Yes (native, ≤3)	As numbered text	Yes (native, ≤13)	—	—	—

A dash (—) means the type is not supported on that channel — sending it returns 400 UNSUPPORTED_MESSAGE_TYPE. FILE is an alias for DOCUMENT.

Text


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "TEXT",
  "text": "Hi Sarah! Your order has been processed 🙌"
}

Image / Video / Audio / Document

Media accepts either a file_id (uploaded via POST /uploads, see below) or a public url:


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "IMAGE",
  "media": { "url": "https://cdn.example.com/promo.jpg", "caption": "New promo!" }
}


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "DOCUMENT",
  "media": { "file_id": "b7c1a0d2-9f3e-4c5a-8b2d-1e2f3a4b5c6d", "filename": "invoice-12345.pdf" }
}

The media's real type must match type — e.g. sending a .pdf as IMAGE is rejected with 400 VALIDATION_ERROR. DOCUMENT accepts any file.

Template (WhatsApp Official only)


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "TEMPLATE",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": { "1": "Sarah", "2": "12345" },
    "media_url": "https://cdn.example.com/header.jpg"
  }
}

variables are keyed "1", "2", … matching the {{1}}, {{2}} placeholders in the template body.
media_url is only needed when the template's header is an image/video/document.
Find your approved templates (name, language, variables) via GET /whatsapp-templates.

:::tip Finding templates

Code
curl "https://api.chatmo.io/v1/open-api/whatsapp-templates?channel_id=92b56f11-...&status=APPROVED" \
  -H "x-api-key: chatmo_live_..."

:::

Interactive (reply buttons)

Native reply buttons on WhatsApp Official (max 3) and Instagram (max 13). On WhatsApp Unofficial they degrade to a numbered-text list; other channels return 400.


Code
{
  "channel_id": "92b56f11-...",
  "to": { "phone": "628123456789" },
  "type": "INTERACTIVE",
  "interactive": {
    "body": "Did your order arrive?",
    "buttons": [
      { "id": "yes", "title": "Yes" },
      { "id": "no", "title": "No" }
    ]
  }
}

The id is the payload echoed back to you when the customer taps the button.

Uploading media

To send media by file_id, upload the file first with POST /uploads (multipart):

Code
curl -X POST https://api.chatmo.io/v1/open-api/uploads \
  -H "x-api-key: chatmo_live_..." \
  -F "file=@/path/to/invoice.pdf"

The response returns an id — pass it as media.file_id. Alternatively, skip the upload entirely and send a public media.url.

Optional fields

Field	Description
`reply_to_message_id`	Native quoted reply — the internal message UUID or the channel-side external id of the parent message.
`client_reference`	Your own correlation id (≤128 chars). Echoed back in the response and stored on the message so you can reconcile later.

Error handling

Errors return a success: false envelope. The human-readable reason is in message; a stable machine code is in data.error_code — switch on that in your integration.


Code
{
  "success": false,
  "code": 400,
  "message": "TEMPLATE messages are only supported on WHATSAPP_OFFICIAL channels",
  "data": { "error_code": "UNSUPPORTED_MESSAGE_TYPE" }
}

HTTP	`error_code`	Meaning
400	`VALIDATION_ERROR`	Missing/invalid field, or media type mismatch.
400	`UNSUPPORTED_MESSAGE_TYPE`	The type isn't supported on that channel.
401	—	Missing or invalid API key.
402	`SUBSCRIPTION_EXPIRED`	Renew your subscription to keep using the API.
403	`FORBIDDEN`	Your key/role lacks permission.
404	`CHANNEL_NOT_FOUND`	Unknown channel or not in your organization.
404	`CONVERSATION_NOT_FOUND`	Unknown `conversation_id`.
404	`TEMPLATE_NOT_FOUND`	No approved template for that name/language/channel.
404	`MEDIA_NOT_FOUND`	`file_id` not found or not finished processing.
422	`CHANNEL_INACTIVE`	The channel isn't active.
502	`PROVIDER_ERROR`	The channel provider rejected the message (detail in `data.detail`). The message is still recorded as `FAILED`.
500	`INTERNAL_ERROR`	Unexpected server error — retry.

Endpoint	Purpose
`GET /channels/by-identifier`	Resolve a `channel_id` from a phone/username/page/widget id.
`GET /inboxes`	List all your channels.
`GET /whatsapp-templates`	List approved WhatsApp templates (name, language, variables).
`POST /uploads`	Upload media and get a `file_id`.
`GET /conversations/{conversation_id}/messages`	Read a conversation's message history.

Last modified on October 14, 2026

Quick start

Step 1 — Get your channel_id

Option A — Look it up by a memorable identifier

Option B — List all your channels

Step 2 — Address the recipient

Message types

Text

Image / Video / Audio / Document

Template (WhatsApp Official only)

Interactive (reply buttons)

Uploading media

Optional fields

Error handling

Related endpoints

Quick start

Step 1 — Get your channel_id

Option A — Look it up by a memorable identifier

Option B — List all your channels

Step 2 — Address the recipient

Message types

Text

Image / Video / Audio / Document

Template (WhatsApp Official only)

Interactive (reply buttons)

Uploading media

Optional fields

Error handling

Related endpoints

Step 1 — Get your `channel_id`

Step 1 — Get your `channel_id`