Get started

OmniMessage documentation

One REST API to send and receive WhatsApp Business, SMS, Telegram, Messenger, Instagram and TikTok messages, billed per outbound message from a prepaid balance.

What OmniMessage is#

OmniMessage is a messaging gateway. You connect your own senders (a WhatsApp Business number, a Telegram bot, an SMS number) as channels, then send every kind of message through one endpoint, POST /v1/messages, with one request shape. Delivery receipts and inbound messages come back to you as signed webhooks.

Billing is prepaid. Each accepted outbound message consumes one credit from a message package or debits a per-message price from your wallet. Messages that fail are refunded automatically, and inbound messages are free.

Base URL#

Base URL

https://api.omnimessage.co/v1

The API is JSON over HTTPS. Send Content-Type: application/json on requests with a body. Field names are snake_case, text is UTF-8 and timestamps are ISO-8601 strings in UTC. Authenticate every request with an API key as a bearer token: see Authentication.

The five-minute path#

Create an account and create a test API key in the console. Test keys start with om_test_.
Send a message to a sandbox channel such as ch_test_whatsapp. Nothing is delivered and nothing is billed.
Read the simulated delivery status back, or receive it on a webhook endpoint.
Connect a real channel and switch to a live key (om_live_) when you are ready.

The quickstart walks through each step with copy-and-paste requests. The first request looks like this:

curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_test_whatsapp",
    "to": "+15550100002",
    "type": "text",
    "text": {
      "body": "Hello from test mode"
    }
  }'

202 Accepted

{
  "id": "msg_7yU2iO5pA8sD1fG4hJ6k",
  "object": "message",
  "mode": "test",
  "channel_id": "ch_test_whatsapp",
  "channel_type": "whatsapp",
  "direction": "outbound",
  "to": "+15550100002",
  "from": "sandbox",
  "type": "text",
  "content": {
    "text": {
      "body": "Hello from test mode"
    }
  },
  "status": "queued",
  "error": null,
  "reference": null,
  "metadata": {},
  "billing": {
    "source": "none",
    "amount_micros": 0,
    "package_grant_id": null,
    "refunded": false
  },
  "sender": null,
  "contact_id": null,
  "created_at": "2026-10-05T09:30:00.000Z",
  "updated_at": "2026-10-05T09:30:02.871Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": null
}

Core concepts#

Concept	What it is	Read more
Channel	One of your own senders, connected with its provider credentials. Each channel has a type and a list of message types it supports.	Channels
Message	An outbound message you send or an inbound message you receive, with a status that advances as delivery progresses.	Sending messages
Webhook endpoint	A URL on your server that receives signed events: status changes, inbound messages, channel and balance events.	Webhooks
Mode	Every key is either live or test. Test mode is a sandbox with simulated delivery and no charges.	Test mode
Wallet and packages	The prepaid funds that pay for outbound messages.	Billing

Conventions#

Topic	Rule
Money	Integer micro-USD in fields ending `_micros` (1 USD = 1,000,000), with `currency: "USD"`. `1000` is $0.001.
IDs	Prefixed, URL-safe strings: `acc_` account, `key_` API key, `ch_` channel, `msg_` message, `we_` webhook endpoint, `evt_` event, `pkg_` package, `grant_` purchased package, `pay_` payment, `txn_` transaction, `req_` request.
Errors	Non-2xx responses carry `{ "error": { "type", "code", "message", ... } }`. See Errors.
Request IDs	Every response has an `X-Request-Id` header. Log it and quote it to support.
Retries	`POST` endpoints accept an `Idempotency-Key` header so retries never send twice. See Idempotency.
Lists	Cursor pagination with `limit` and `starting_after`. See Pagination.
Limits	100 requests per second on `POST /v1/messages`, 20 per second elsewhere, per API key. See Rate limits.

What OmniMessage is#

Base URL#

The five-minute path#

Core concepts#

Conventions#

Explore#