API reference

Messages

Send messages on any connected channel, alone or in batches, and read back their status and history.

Send a message#

POST/v1/messagesScopemessages:write

Queues one message for delivery on a channel and charges for it.

Provide type and the content object under the key named by type. The types a channel accepts are listed in its capabilities.

Billing happens at acceptance: one package credit if an applicable package has credits (earliest expiry first), otherwise the per-message price of the channel type is debited from the wallet. If neither is possible the request fails with 402 insufficient_balance and no message is created. A message that later fails is refunded automatically. Test-mode messages are never billed.

The response is 202 Accepted with status: "queued". Delivery is asynchronous: follow the outcome through webhooks or by retrieving the message.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

channelstringRequired
ID of the channel to send from. In test mode, a sandbox channel such as ch_test_whatsapp.
1 to 64 characters
tostringRequired
Recipient identifier: E.164 phone number for WhatsApp and SMS, chat ID for Telegram, page-scoped user ID for Messenger and Instagram.
1 to 255 characters
typestringRequired
Content type. Must be listed in the channel capabilities.
1 to 64 characters
textobjectOptional
Plain text. Supported on every channel.
Show child attributesHide child attributes
- bodystringRequired
  Message text, 1 to 4096 characters.
  1 to 4096 characters
- preview_urlbooleanOptional
  Ask the channel to render a preview for the first URL in body, where the channel supports it.
attachmentsarray of objectsOptional
A media message. The array must contain exactly one item. Supported on every channel except sms_otp.
Exactly 1 item
Show child attributesHide child attributes
- typestringRequired
  Kind of media.
  Possible valuesimagevideodocumentaudiovoicesticker
- urlstringRequired
  Publicly reachable HTTPS URL of the file. It is fetched at send time.
- captionstringOptional
  Text shown with the media, where the channel supports captions.
  Up to 1024 characters
- filenamestringOptional
  File name shown to the recipient for documents.
  Up to 255 characters
templateobjectOptional
A pre-approved WhatsApp message template. Required to start a conversation outside the 24-hour customer service window.
Show child attributesHide child attributes
- namestringRequired
  Template name as approved in WhatsApp Manager.
  1 to 512 characters
- languageobjectRequired
  Template language.
  Show child attributesHide child attributes
  codestringRequired
  Language or locale code of the approved translation, for example en or en_US.
  2 to 15 characters
- componentsarray of objectsOptional
  Values for the template variables, in the WhatsApp Cloud API component format. Omit for templates without variables.
  Show child attributesHide child attributes
  typestringRequired
  Which part of the template the parameters fill.
  Possible valuesheaderbodybutton
  sub_typestringOptional
  Button kind, for button components (for example url or quick_reply).
  indexstringOptional
  Zero-based button position, for button components.
  parametersarray of objectsOptional
  Parameter values in template order.
buttonobjectOptional
A message with one to three quick-reply buttons. A tap arrives as an inbound message carrying the button id.
Show child attributesHide child attributes
- headerobjectOptional
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestringRequired
  Header kind.
  Possible valuestext
  textstringRequired
  Header text, up to 60 characters.
  1 to 60 characters
- bodyobjectRequired
  Main message text.
  Show child attributesHide child attributes
  textstringRequired
  Body text.
  1 to 1024 characters
- footerobjectOptional
  Optional small print below the body.
  Show child attributesHide child attributes
  textstringRequired
  Footer text, up to 60 characters.
  1 to 60 characters
- actionobjectRequired
  The buttons.
  Show child attributesHide child attributes
  buttonsarray of objectsRequired
  One to three reply buttons.
  1 to 3 items
  Show child attributesHide child attributes
  replyobjectRequired
  A reply button.
  Show child attributesHide child attributes
  idstringRequired
  Your identifier for the button. Returned when the recipient taps it.
  1 to 256 characters
  titlestringRequired
  Button label, up to 20 characters.
  1 to 20 characters
listobjectOptional
A WhatsApp list picker: one button that opens a menu of rows grouped into sections.
Show child attributesHide child attributes
- headerobjectOptional
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestringRequired
  Header kind.
  Possible valuestext
  textstringRequired
  Header text, up to 60 characters.
  1 to 60 characters
- bodyobjectRequired
  Main message text.
  Show child attributesHide child attributes
  textstringRequired
  Body text.
  1 to 1024 characters
- footerobjectOptional
  Optional small print below the body.
  Show child attributesHide child attributes
  textstringRequired
  Footer text, up to 60 characters.
  1 to 60 characters
- actionobjectRequired
  The menu.
  Show child attributesHide child attributes
  buttonstringRequired
  Label of the button that opens the list, up to 20 characters.
  1 to 20 characters
  sectionsarray of objectsRequired
  Groups of rows.
  Show child attributesHide child attributes
  titlestringRequired
  Section heading, up to 24 characters.
  1 to 24 characters
  rowsarray of objectsRequired
  Selectable rows.
  Show child attributesHide child attributes
  idstringRequired
  Your identifier for the row. Returned when the recipient selects it.
  1 to 200 characters
  titlestringRequired
  Row label, up to 24 characters.
  1 to 24 characters
  descriptionstringOptional
  Optional second line, up to 72 characters.
  Up to 72 characters
cta_urlobjectOptional
A WhatsApp message with a single button that opens a URL.
Show child attributesHide child attributes
- headerobjectOptional
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestringRequired
  Header kind.
  Possible valuestext
  textstringRequired
  Header text, up to 60 characters.
  1 to 60 characters
- bodyobjectRequired
  Main message text.
  Show child attributesHide child attributes
  textstringRequired
  Body text.
  1 to 1024 characters
- footerobjectOptional
  Optional small print below the body.
  Show child attributesHide child attributes
  textstringRequired
  Footer text, up to 60 characters.
  1 to 60 characters
- actionobjectRequired
  The link button.
  Show child attributesHide child attributes
  parametersobjectRequired
  Show child attributesHide child attributes
  display_textstringRequired
  Button label, up to 20 characters.
  1 to 20 characters
  urlstringRequired
  URL opened when the button is tapped.
locationobjectOptional
A map pin. Supported on WhatsApp and Telegram.
Show child attributesHide child attributes
- latitudenumberRequired
  Latitude in decimal degrees.
  -90 to 90
- longitudenumberRequired
  Longitude in decimal degrees.
  -180 to 180
- namestringRequired
  Name of the place.
  Up to 255 characters
- addressstringRequired
  Address of the place.
  Up to 1024 characters
contactsarray of objectsOptional
One or more contact cards in the provider contact format. Forwarded to the channel without further validation. Supported on WhatsApp and Telegram.
Show child attributesHide child attributes
- nameobjectOptional
  Contact name.
  Show child attributesHide child attributes
  formatted_namestringRequired
  Full display name.
  first_namestringOptional
  Given name.
  last_namestringOptional
  Family name.
- phonesarray of objectsOptional
  Phone numbers.
  Show child attributesHide child attributes
  phonestringOptional
  Phone number in E.164 format.
  typestringOptional
  Label such as CELL, WORK or HOME.
pollobjectOptional
A Telegram poll.
Show child attributesHide child attributes
- questionstringRequired
  Poll question, up to 300 characters.
  1 to 300 characters
- optionsarray of stringsRequired
  Two to ten answer options of up to 100 characters each.
  2 to 10 items
reply_tostringOptional
ID of a message on the same channel to quote. A message that does not exist, or that belongs to another channel or mode, fails with 404 resource_missing.
1 to 64 characters
referencestringOptional
Your own identifier for the message. Returned on the message and usable as a list filter.
1 to 255 characters
metadataobjectOptional
Up to 20 string keys of up to 64 characters with string values of up to 500 characters. Returned on the message and in webhook events.
Up to 20 keys

Responses

202
Accepted. The message is queued and has been charged. Message object.
400
Bad request.
parameter_missing parameter_invalid unsupported_message_type invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
402
No package credits remain and the wallet cannot cover the message price. Nothing was created.
insufficient_balance
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The channel (or the reply_to message) does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
422
The channel cannot take the message. The charge was reversed and no message was created.
channel_not_connected recipient_blocked policy_violation upstream_rejected
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error
503
The delivery layer is temporarily unavailable. Any charge was reversed and nothing was created.
upstream_unavailable

POST/v1/messages

Example

curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-3b7d-4c59-9f0a-2d8e5b1c7a43" \
  -d '{
    "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
    "to": "+971501234567",
    "type": "text",
    "text": {
      "body": "Your code is 482910"
    },
    "reference": "order-1042",
    "metadata": {
      "user_id": "u_17"
    }
  }'

Response · 202

{
  "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
  "object": "message",
  "mode": "live",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "direction": "outbound",
  "to": "+971501234567",
  "from": "+971800123456",
  "type": "text",
  "content": {
    "text": {
      "body": "Your code is 482910"
    }
  },
  "status": "queued",
  "error": null,
  "reference": "order-1042",
  "metadata": {
    "user_id": "u_17"
  },
  "billing": {
    "source": "package",
    "amount_micros": 0,
    "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
    "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
}

List messages#

GET/v1/messagesScopemessages:read

Returns messages of the key mode, newest first. Combine filters to narrow the result; all filters are exact matches.

Query parameters

channelstringOptional
Only messages on this channel ID.
directionstringOptional
Only outbound or only inbound messages.
Possible valuesoutboundinbound
statusstringOptional
Only messages currently in this status.
Possible valuesqueuedsendingsentdeliveredreadfailedreceived
tostringOptional
Only messages to this recipient identifier.
referencestringOptional
Only messages with this reference.
created_aftertimestampOptional
Only messages created after this ISO-8601 timestamp.
created_beforetimestampOptional
Only messages created before this ISO-8601 timestamp.
updated_aftertimestampOptional
Only messages that changed after this ISO-8601 timestamp (updated_at): new messages and status changes alike. The order stays newest created first. For polling.
limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of messages.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/messages

curl "https://api.omnimessage.co/v1/messages?to=%2B971501234567&reference=order-1042&created_after=2026-10-05T00%3A00%3A00Z&updated_after=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "object": "message",
      "mode": "live",
      "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
      "channel_type": "whatsapp",
      "direction": "outbound",
      "to": "+971501234567",
      "from": "+971800123456",
      "type": "text",
      "content": {
        "text": {
          "body": "Your code is 482910"
        }
      },
      "status": "delivered",
      "error": null,
      "reference": "order-1042",
      "metadata": {
        "user_id": "u_17"
      },
      "billing": {
        "source": "package",
        "amount_micros": 0,
        "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
        "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": "2026-10-05T09:30:01.210Z",
      "delivered_at": "2026-10-05T09:30:02.871Z",
      "read_at": null,
      "failed_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "msg_2b1Xw9aQ3rT8yU0pL4kZ"
}

Send a batch of messages#

POST/v1/messages/batchScopemessages:write

Sends up to 100 messages in one request. Each item has the same shape as the body of POST /v1/messages, is validated, billed and accepted independently, and may target a different channel.

The response is 207 Multi-Status whenever the batch itself was well-formed, even if every item was rejected. Inspect data[].status per item: accepted items carry message, rejected items carry error. Idempotency-Key applies to the batch as a whole.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

messagesarray of objectsRequired
One to 100 messages. Each item has the same shape as the body of POST /v1/messages.
1 to 100 items
Show child attributesHide child attributes
- channelstringRequired
  ID of the channel to send from. In test mode, a sandbox channel such as ch_test_whatsapp.
  1 to 64 characters
- tostringRequired
  Recipient identifier: E.164 phone number for WhatsApp and SMS, chat ID for Telegram, page-scoped user ID for Messenger and Instagram.
  1 to 255 characters
- typestringRequired
  Content type. Must be listed in the channel capabilities.
  1 to 64 characters
- textobjectOptional
  Plain text. Supported on every channel.
  Show child attributesHide child attributes
  bodystringRequired
  Message text, 1 to 4096 characters.
  1 to 4096 characters
  preview_urlbooleanOptional
  Ask the channel to render a preview for the first URL in body, where the channel supports it.
- attachmentsarray of objectsOptional
  A media message. The array must contain exactly one item. Supported on every channel except sms_otp.
  Exactly 1 item
  Show child attributesHide child attributes
  typestringRequired
  Kind of media.
  Possible valuesimagevideodocumentaudiovoicesticker
  urlstringRequired
  Publicly reachable HTTPS URL of the file. It is fetched at send time.
  captionstringOptional
  Text shown with the media, where the channel supports captions.
  Up to 1024 characters
  filenamestringOptional
  File name shown to the recipient for documents.
  Up to 255 characters
- templateobjectOptional
  A pre-approved WhatsApp message template. Required to start a conversation outside the 24-hour customer service window.
  Show child attributesHide child attributes
  namestringRequired
  Template name as approved in WhatsApp Manager.
  1 to 512 characters
  languageobjectRequired
  Template language.
  Show child attributesHide child attributes
  codestringRequired
  Language or locale code of the approved translation, for example en or en_US.
  2 to 15 characters
  componentsarray of objectsOptional
  Values for the template variables, in the WhatsApp Cloud API component format. Omit for templates without variables.
  Show child attributesHide child attributes
  typestringRequired
  Which part of the template the parameters fill.
  Possible valuesheaderbodybutton
  sub_typestringOptional
  Button kind, for button components (for example url or quick_reply).
  indexstringOptional
  Zero-based button position, for button components.
  parametersarray of objectsOptional
  Parameter values in template order.
- buttonobjectOptional
  A message with one to three quick-reply buttons. A tap arrives as an inbound message carrying the button id.
  Show child attributesHide child attributes
  headerobjectOptional
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestringRequired
  Header kind.
  Possible valuestext
  textstringRequired
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobjectRequired
  Main message text.
  Show child attributesHide child attributes
  textstringRequired
  Body text.
  1 to 1024 characters
  footerobjectOptional
  Optional small print below the body.
  Show child attributesHide child attributes
  textstringRequired
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobjectRequired
  The buttons.
  Show child attributesHide child attributes
  buttonsarray of objectsRequired
  One to three reply buttons.
  1 to 3 items
  Show child attributesHide child attributes
  replyobjectRequired
  A reply button.
  Show child attributesHide child attributes
  idstringRequired
  Your identifier for the button. Returned when the recipient taps it.
  1 to 256 characters
  titlestringRequired
  Button label, up to 20 characters.
  1 to 20 characters
- listobjectOptional
  A WhatsApp list picker: one button that opens a menu of rows grouped into sections.
  Show child attributesHide child attributes
  headerobjectOptional
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestringRequired
  Header kind.
  Possible valuestext
  textstringRequired
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobjectRequired
  Main message text.
  Show child attributesHide child attributes
  textstringRequired
  Body text.
  1 to 1024 characters
  footerobjectOptional
  Optional small print below the body.
  Show child attributesHide child attributes
  textstringRequired
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobjectRequired
  The menu.
  Show child attributesHide child attributes
  buttonstringRequired
  Label of the button that opens the list, up to 20 characters.
  1 to 20 characters
  sectionsarray of objectsRequired
  Groups of rows.
  Show child attributesHide child attributes
  titlestringRequired
  Section heading, up to 24 characters.
  1 to 24 characters
  rowsarray of objectsRequired
  Selectable rows.
  Show child attributesHide child attributes
  idstringRequired
  Your identifier for the row. Returned when the recipient selects it.
  1 to 200 characters
  titlestringRequired
  Row label, up to 24 characters.
  1 to 24 characters
  descriptionstringOptional
  Optional second line, up to 72 characters.
  Up to 72 characters
- cta_urlobjectOptional
  A WhatsApp message with a single button that opens a URL.
  Show child attributesHide child attributes
  headerobjectOptional
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestringRequired
  Header kind.
  Possible valuestext
  textstringRequired
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobjectRequired
  Main message text.
  Show child attributesHide child attributes
  textstringRequired
  Body text.
  1 to 1024 characters
  footerobjectOptional
  Optional small print below the body.
  Show child attributesHide child attributes
  textstringRequired
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobjectRequired
  The link button.
  Show child attributesHide child attributes
  parametersobjectRequired
  Show child attributesHide child attributes
  display_textstringRequired
  Button label, up to 20 characters.
  1 to 20 characters
  urlstringRequired
  URL opened when the button is tapped.
- locationobjectOptional
  A map pin. Supported on WhatsApp and Telegram.
  Show child attributesHide child attributes
  latitudenumberRequired
  Latitude in decimal degrees.
  -90 to 90
  longitudenumberRequired
  Longitude in decimal degrees.
  -180 to 180
  namestringRequired
  Name of the place.
  Up to 255 characters
  addressstringRequired
  Address of the place.
  Up to 1024 characters
- contactsarray of objectsOptional
  One or more contact cards in the provider contact format. Forwarded to the channel without further validation. Supported on WhatsApp and Telegram.
  Show child attributesHide child attributes
  nameobjectOptional
  Contact name.
  Show child attributesHide child attributes
  formatted_namestringRequired
  Full display name.
  first_namestringOptional
  Given name.
  last_namestringOptional
  Family name.
  phonesarray of objectsOptional
  Phone numbers.
  Show child attributesHide child attributes
  phonestringOptional
  Phone number in E.164 format.
  typestringOptional
  Label such as CELL, WORK or HOME.
- pollobjectOptional
  A Telegram poll.
  Show child attributesHide child attributes
  questionstringRequired
  Poll question, up to 300 characters.
  1 to 300 characters
  optionsarray of stringsRequired
  Two to ten answer options of up to 100 characters each.
  2 to 10 items
- reply_tostringOptional
  ID of a message on the same channel to quote. A message that does not exist, or that belongs to another channel or mode, fails with 404 resource_missing.
  1 to 64 characters
- referencestringOptional
  Your own identifier for the message. Returned on the message and usable as a list filter.
  1 to 255 characters
- metadataobjectOptional
  Up to 20 string keys of up to 64 characters with string values of up to 500 characters. Returned on the message and in webhook events.
  Up to 20 keys

Responses

207
Per-item results, in request order. Batch result object.
400
The batch envelope is malformed: messages is missing, empty or longer than 100 items.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/messages/batch

curl https://api.omnimessage.co/v1/messages/batch \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-3b7d-4c59-9f0a-2d8e5b1c7a43" \
  -d '{
    "messages": [
      {
        "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
        "to": "+971501234567",
        "type": "text",
        "text": {
          "body": "Your order has shipped."
        },
        "reference": "order-1042"
      },
      {
        "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
        "to": "+971509876543",
        "type": "text",
        "text": {
          "body": "Your order has shipped."
        },
        "reference": "order-1043"
      }
    ]
  }'

Response · 207

{
  "object": "batch",
  "data": [
    {
      "index": 0,
      "status": 202,
      "message": {
        "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
        "object": "message",
        "mode": "live",
        "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
        "channel_type": "whatsapp",
        "direction": "outbound",
        "to": "+971501234567",
        "from": "+971800123456",
        "type": "text",
        "content": {
          "text": {
            "body": "Your code is 482910"
          }
        },
        "status": "queued",
        "error": null,
        "reference": "order-1042",
        "metadata": {},
        "billing": {
          "source": "package",
          "amount_micros": 0,
          "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
          "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
      }
    },
    {
      "index": 1,
      "status": 402,
      "error": {
        "type": "billing_error",
        "code": "insufficient_balance",
        "message": "No package credits remain and the wallet balance is below the message price.",
        "request_id": "req_0aB3cD6eF9gH2iJ5kL8m",
        "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance"
      }
    }
  ],
  "accepted": 1,
  "rejected": 1
}

Retrieve a message#

GET/v1/messages/{id}Scopemessages:read

Returns one message with its current status, billing outcome and timestamps.

Path parameters

idstringRequired
Message ID.

Responses

200
The message. Message object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/messages/{id}

curl https://api.omnimessage.co/v1/messages/msg_2b1Xw9aQ3rT8yU0pL4kZ \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
  "object": "message",
  "mode": "live",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "direction": "outbound",
  "to": "+971501234567",
  "from": "+971800123456",
  "type": "text",
  "content": {
    "text": {
      "body": "Your code is 482910"
    }
  },
  "status": "delivered",
  "error": null,
  "reference": "order-1042",
  "metadata": {
    "user_id": "u_17"
  },
  "billing": {
    "source": "package",
    "amount_micros": 0,
    "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
    "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": "2026-10-05T09:30:01.210Z",
  "delivered_at": "2026-10-05T09:30:02.871Z",
  "read_at": null,
  "failed_at": null
}

List message status events#

GET/v1/messages/{id}/eventsScopemessages:read

Returns the full status history of a message, oldest first. Useful for debugging delivery timing. The list is not paginated.

Path parameters

idstringRequired
Message ID.

Responses

200
Status history.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/messages/{id}/events

curl https://api.omnimessage.co/v1/messages/msg_2b1Xw9aQ3rT8yU0pL4kZ/events \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "status": "queued",
      "description": "Accepted and charged.",
      "occurred_at": "2026-10-05T09:30:00.000Z"
    },
    {
      "status": "sending",
      "description": "Handed to the channel.",
      "occurred_at": "2026-10-05T09:30:00.412Z"
    },
    {
      "status": "sent",
      "description": "Accepted by the provider.",
      "occurred_at": "2026-10-05T09:30:01.210Z"
    },
    {
      "status": "delivered",
      "description": "Delivered to the recipient device.",
      "occurred_at": "2026-10-05T09:30:02.871Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Simulate an inbound message#

POST/v1/test/inbound_messagesScopemessages:write

Test mode only. Stores an inbound message as if a customer had written to a sandbox channel and emits message.received, so that "message received" triggers can be built and demonstrated without a live channel. Nothing is billed, and stop keywords are not applied.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

channelstringRequired
A sandbox channel (ch_test_<type>) or a channel created in test mode.
fromstringRequired
The sender: an E.164 phone number for WhatsApp and SMS, a chat or user ID elsewhere.
1 to 255 characters
typestringOptional
Only text can be simulated.
Value: text
textobjectRequired
Show child attributesHide child attributes
- bodystringRequired
  Message text.
  1 to 4096 characters
senderobjectOptional
Profile to report as the sender.
Show child attributesHide child attributes
- namestringOptional
  Up to 255 characters
- usernamestringOptional
  Up to 255 characters

Responses

201
The inbound message. Message object.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The key may not call the operation, or it is a live key.
scope_missing ip_not_allowed account_suspended test_mode_required
404
The channel is not a sandbox or test-mode channel of this account.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/test/inbound_messages

curl https://api.omnimessage.co/v1/test/inbound_messages \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-3b7d-4c59-9f0a-2d8e5b1c7a43" \
  -d '{
    "channel": "ch_test_whatsapp",
    "from": "+971501234567",
    "type": "text",
    "text": {
      "body": "Where is my order?"
    },
    "sender": {
      "name": "Layla Hassan"
    }
  }'

Response · 201

{
  "id": "msg_4fD8sA1gH6jK9lZ3xC5v",
  "object": "message",
  "mode": "test",
  "channel_id": "ch_test_whatsapp",
  "channel_type": "whatsapp",
  "direction": "inbound",
  "to": "sandbox",
  "from": "+971501234567",
  "type": "text",
  "content": {
    "text": {
      "body": "Where is my order?"
    }
  },
  "status": "received",
  "error": null,
  "reference": null,
  "metadata": {},
  "billing": {
    "source": "none",
    "amount_micros": 0,
    "package_grant_id": null,
    "refunded": false
  },
  "sender": {
    "name": "Layla Hassan",
    "username": null
  },
  "contact_id": null,
  "created_at": "2026-10-05T09:42:10.000Z",
  "updated_at": "2026-10-05T09:42:10.000Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": null
}