API reference

Objects

The resources the API returns, with every attribute and an example. Attributes marked "or null" are always present and may be null.

The message object#

An outbound message you sent, or an inbound message received on one of your channels.

Attributes

idstring
Unique identifier, prefixed msg_.
objectstring
Always message.
Value: message
modestring
Mode of the API key that created the message.
Possible valueslivetest
channel_idstring
Channel the message was sent or received on.
channel_typestring
Type of that channel.
Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
directionstring
outbound for messages you send, inbound for messages you receive.
Possible valuesoutboundinbound
tostring
Recipient identifier. For inbound messages, the identifier of your channel.
fromstring
Sender identifier. For outbound messages, the identifier of your channel.
typestring
Content type. One of the common types (text, attachments, template, button, list, cta_url, location, contacts, poll) or a channel-specific type listed in the channel capabilities.
contentobject
The content, under a single key equal to type.
Show child attributesHide child attributes
- textobject
  Plain text. Supported on every channel.
  Show child attributesHide child attributes
  bodystring
  Message text, 1 to 4096 characters.
  1 to 4096 characters
  preview_urlboolean
  Ask the channel to render a preview for the first URL in body, where the channel supports it.
- attachmentsarray of objects
  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
  typestring
  Kind of media.
  Possible valuesimagevideodocumentaudiovoicesticker
  urlstring
  Publicly reachable HTTPS URL of the file. It is fetched at send time.
  captionstring
  Text shown with the media, where the channel supports captions.
  Up to 1024 characters
  filenamestring
  File name shown to the recipient for documents.
  Up to 255 characters
- templateobject
  A pre-approved WhatsApp message template. Required to start a conversation outside the 24-hour customer service window.
  Show child attributesHide child attributes
  namestring
  Template name as approved in WhatsApp Manager.
  1 to 512 characters
  languageobject
  Template language.
  Show child attributesHide child attributes
  codestring
  Language or locale code of the approved translation, for example en or en_US.
  2 to 15 characters
  componentsarray of objects
  Values for the template variables, in the WhatsApp Cloud API component format. Omit for templates without variables.
  Show child attributesHide child attributes
  typestring
  Which part of the template the parameters fill.
  Possible valuesheaderbodybutton
  sub_typestring
  Button kind, for button components (for example url or quick_reply).
  indexstring
  Zero-based button position, for button components.
  parametersarray of objects
  Parameter values in template order.
- buttonobject
  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
  headerobject
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestring
  Header kind.
  Possible valuestext
  textstring
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobject
  Main message text.
  Show child attributesHide child attributes
  textstring
  Body text.
  1 to 1024 characters
  footerobject
  Optional small print below the body.
  Show child attributesHide child attributes
  textstring
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobject
  The buttons.
  Show child attributesHide child attributes
  buttonsarray of objects
  One to three reply buttons.
  1 to 3 items
  Show child attributesHide child attributes
  replyobject
  A reply button.
  Show child attributesHide child attributes
  idstring
  Your identifier for the button. Returned when the recipient taps it.
  1 to 256 characters
  titlestring
  Button label, up to 20 characters.
  1 to 20 characters
- listobject
  A WhatsApp list picker: one button that opens a menu of rows grouped into sections.
  Show child attributesHide child attributes
  headerobject
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestring
  Header kind.
  Possible valuestext
  textstring
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobject
  Main message text.
  Show child attributesHide child attributes
  textstring
  Body text.
  1 to 1024 characters
  footerobject
  Optional small print below the body.
  Show child attributesHide child attributes
  textstring
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobject
  The menu.
  Show child attributesHide child attributes
  buttonstring
  Label of the button that opens the list, up to 20 characters.
  1 to 20 characters
  sectionsarray of objects
  Groups of rows.
  Show child attributesHide child attributes
  titlestring
  Section heading, up to 24 characters.
  1 to 24 characters
  rowsarray of objects
  Selectable rows.
  Show child attributesHide child attributes
  idstring
  Your identifier for the row. Returned when the recipient selects it.
  1 to 200 characters
  titlestring
  Row label, up to 24 characters.
  1 to 24 characters
  descriptionstring
  Optional second line, up to 72 characters.
  Up to 72 characters
- cta_urlobject
  A WhatsApp message with a single button that opens a URL.
  Show child attributesHide child attributes
  headerobject
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestring
  Header kind.
  Possible valuestext
  textstring
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobject
  Main message text.
  Show child attributesHide child attributes
  textstring
  Body text.
  1 to 1024 characters
  footerobject
  Optional small print below the body.
  Show child attributesHide child attributes
  textstring
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobject
  The link button.
  Show child attributesHide child attributes
  parametersobject
  Show child attributesHide child attributes
  display_textstring
  Button label, up to 20 characters.
  1 to 20 characters
  urlstring
  URL opened when the button is tapped.
- locationobject
  A map pin. Supported on WhatsApp and Telegram.
  Show child attributesHide child attributes
  latitudenumber
  Latitude in decimal degrees.
  -90 to 90
  longitudenumber
  Longitude in decimal degrees.
  -180 to 180
  namestring
  Name of the place.
  Up to 255 characters
  addressstring
  Address of the place.
  Up to 1024 characters
- contactsarray of objects
  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
  nameobject
  Contact name.
  Show child attributesHide child attributes
  formatted_namestring
  Full display name.
  first_namestring
  Given name.
  last_namestring
  Family name.
  phonesarray of objects
  Phone numbers.
  Show child attributesHide child attributes
  phonestring
  Phone number in E.164 format.
  typestring
  Label such as CELL, WORK or HOME.
- pollobject
  A Telegram poll.
  Show child attributesHide child attributes
  questionstring
  Poll question, up to 300 characters.
  1 to 300 characters
  optionsarray of strings
  Two to ten answer options of up to 100 characters each.
  2 to 10 items
statusstring
Delivery status. Outbound: queued, sending, sent, delivered, read or failed. Inbound: received.
Possible valuesqueuedsendingsentdeliveredreadfailedreceived
errorobject or null
Why the message failed. null unless status is failed.
Show child attributesHide child attributes
- codestring
  Failure reason. provider_error when the channel provider rejected or could not deliver the message.
- messagestring
  Human-readable explanation.
- provider_codestring or null
  Error code returned by the channel provider. null when the provider gave none.
referencestring or null
Your own identifier, as supplied when sending.
Up to 255 characters
metadataobject
Key-value pairs supplied when sending. Empty object if none.
billingobject
How the message was paid for.
Show child attributesHide child attributes
- sourcestring
  package: one package credit was consumed. wallet: amount_micros was debited from the wallet. none: not billed (test mode and inbound messages).
  Possible valuespackagewalletnone
- amount_microsinteger
  Amount debited from the wallet in micro-USD. 0 unless source is wallet.
- package_grant_idstring or null
  Package the credit came from, when source is package.
- refundedboolean
  Whether the charge was returned because the message failed.
senderobject or null
Inbound messages: what the channel reported about the sender. null on outbound messages and when the channel reported nothing.
Show child attributesHide child attributes
- namestring or null
  Display name the sender has on the channel (the WhatsApp profile name, the Telegram first and last name).
- usernamestring or null
  Handle on the channel, where the channel has one (Telegram, Instagram).
contact_idstring or null
Inbound messages: the contact that had the sender's identifier when the message arrived (ct_…), or null when there is none. Always null on outbound messages.
created_attimestamp
When the message was accepted or received.
updated_attimestamp
When the message last changed: usually its latest status change. Filter on it with updated_after.
sent_atstring or null
When the provider accepted the message.
delivered_atstring or null
When the message reached the recipient device.
read_atstring or null
When the recipient read the message, on channels that report it.
failed_atstring or null
When the message failed.

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": "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
}

The channel object#

A sender you connected: a WhatsApp Business number, a Telegram bot, an SMS number and so on.

Attributes

idstring
Unique identifier, prefixed ch_. Sandbox channels use ch_test_<type>.
objectstring
Always channel.
Value: channel
modestring
test for the built-in sandbox channels, live for connected channels.
Possible valueslivetest
typestring
Channel type.
Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
namestring
Display name you chose.
identifierstring
Sender identity on the channel: phone number, bot username, sender ID, page ID or account ID. Always sandbox for the built-in sandbox channels.
statusstring
suspended channels cannot send.
Possible valuesactivesuspended
connection_statusstring
State of the link to the provider. Messages can be sent only while connected.
Possible valuespendingconnectedreconnectingdisconnectedblocked
capabilitiesarray of strings
Message types the channel accepts as type when sending.
created_attimestamp
When the channel was created.

Channel

{
  "id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "object": "channel",
  "mode": "live",
  "type": "whatsapp",
  "name": "Support line",
  "identifier": "+971800123456",
  "status": "active",
  "connection_status": "connected",
  "capabilities": [
    "text",
    "attachments",
    "template",
    "button",
    "list",
    "cta_url",
    "location",
    "contacts",
    "flow",
    "product",
    "product_list",
    "catalog",
    "carousel",
    "location_request"
  ],
  "created_at": "2026-10-01T08:00:00.000Z"
}

The webhook endpoint object#

A URL on your server that receives events.

Attributes

idstring
Unique identifier, prefixed we_.
objectstring
Always webhook_endpoint.
Value: webhook_endpoint
modestring
Mode of the API key that created the endpoint. The endpoint receives events of this mode only.
Possible valueslivetest
urlstring
HTTPS URL that receives the events.
descriptionstring or null
Your note about the endpoint.
eventsarray of strings
Subscribed event types. ["*"] means all.
Possible valuesmessage.sentmessage.deliveredmessage.readmessage.failedmessage.receivedchannel.connectedchannel.disconnectedbalance.lowpackage.exhaustedpackage.expiringcampaign.startedcampaign.pausedcampaign.completedcampaign.failed*
statusstring
disabled endpoints receive nothing. An endpoint is disabled automatically after 50 consecutive failed deliveries.
Possible valuesactivedisabled
filtersobject
Server-side filters. An event is delivered only when it matches every filter that is set; events that do not carry the filtered property (for example balance.low) always pass.
Show child attributesHide child attributes
- channel_idstring
  Only events about this channel: messages on it, and its own channel.* events.
- directionstring
  Only message events of this direction.
  Possible valuesoutboundinbound
metadataobject
Key-value pairs supplied by whoever created the endpoint, for its own bookkeeping. Empty object if none.
sourcestring or null
The tool that owns the endpoint (zapier, n8n, make…), or null for an endpoint created by hand. An endpoint with a source is removed automatically after 30 days of uninterrupted failures.
created_byobject or null
Who created the endpoint. null for endpoints older than this field.
Show child attributesHide child attributes
- typestring
  A console user or an API key.
  Possible valuesuserapi_key
- idstring
  ID of that user or key.
has_verification_tokenboolean
Whether deliveries carry the OmniMessage-Verification-Token header. The token itself is never returned.
secretstring
Signing secret, prefixed whsec_. Returned only when the endpoint is created and when the secret is rolled.
created_attimestamp
When the endpoint was created.

Webhook endpoint

{
  "id": "we_3kL9pQ2wE5rT8yU1iO4a",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://example.com/hooks/omni",
  "description": "Production delivery receipts",
  "events": [
    "message.delivered",
    "message.failed",
    "message.received"
  ],
  "status": "active",
  "filters": {},
  "metadata": {},
  "source": null,
  "created_by": {
    "type": "api_key",
    "id": "key_1qW4eR7tY0uI3oP6aS9d"
  },
  "has_verification_token": false,
  "created_at": "2026-10-02T11:15:00.000Z"
}

The event object#

The body of every webhook request.

Attributes

idstring
Unique identifier, prefixed evt_. Stable across retries: use it to deduplicate.
objectstring
Always event.
Value: event
typestring
Event type.
Possible valuesmessage.sentmessage.deliveredmessage.readmessage.failedmessage.receivedchannel.connectedchannel.disconnectedbalance.lowpackage.exhaustedpackage.expiringcampaign.startedcampaign.pausedcampaign.completedcampaign.failedwebhook.test
modestring
Mode the event belongs to.
Possible valueslivetest
created_attimestamp
When the event occurred.
dataobject
Event payload.
Show child attributesHide child attributes
- objectobject
  The resource the event is about, as it was when the event occurred: a message for message.*, a channel for channel.*, the balance for balance.low, a package for package.*, a campaign for campaign.*.
  Message · show attributes · hide attributes
  idstring
  Unique identifier, prefixed msg_.
  objectstring
  Always message.
  Value: message
  modestring
  Mode of the API key that created the message.
  Possible valueslivetest
  channel_idstring
  Channel the message was sent or received on.
  channel_typestring
  Type of that channel.
  Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
  directionstring
  outbound for messages you send, inbound for messages you receive.
  Possible valuesoutboundinbound
  tostring
  Recipient identifier. For inbound messages, the identifier of your channel.
  fromstring
  Sender identifier. For outbound messages, the identifier of your channel.
  typestring
  Content type. One of the common types (text, attachments, template, button, list, cta_url, location, contacts, poll) or a channel-specific type listed in the channel capabilities.
  contentobject
  The content, under a single key equal to type.
  Show child attributesHide child attributes
  textobject
  Plain text. Supported on every channel.
  Show child attributesHide child attributes
  bodystring
  Message text, 1 to 4096 characters.
  1 to 4096 characters
  preview_urlboolean
  Ask the channel to render a preview for the first URL in body, where the channel supports it.
  attachmentsarray of objects
  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
  typestring
  Kind of media.
  Possible valuesimagevideodocumentaudiovoicesticker
  urlstring
  Publicly reachable HTTPS URL of the file. It is fetched at send time.
  captionstring
  Text shown with the media, where the channel supports captions.
  Up to 1024 characters
  filenamestring
  File name shown to the recipient for documents.
  Up to 255 characters
  templateobject
  A pre-approved WhatsApp message template. Required to start a conversation outside the 24-hour customer service window.
  Show child attributesHide child attributes
  namestring
  Template name as approved in WhatsApp Manager.
  1 to 512 characters
  languageobject
  Template language.
  Show child attributesHide child attributes
  codestring
  Language or locale code of the approved translation, for example en or en_US.
  2 to 15 characters
  componentsarray of objects
  Values for the template variables, in the WhatsApp Cloud API component format. Omit for templates without variables.
  Show child attributesHide child attributes
  typestring
  Which part of the template the parameters fill.
  Possible valuesheaderbodybutton
  sub_typestring
  Button kind, for button components (for example url or quick_reply).
  indexstring
  Zero-based button position, for button components.
  parametersarray of objects
  Parameter values in template order.
  buttonobject
  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
  headerobject
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestring
  Header kind.
  Possible valuestext
  textstring
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobject
  Main message text.
  Show child attributesHide child attributes
  textstring
  Body text.
  1 to 1024 characters
  footerobject
  Optional small print below the body.
  Show child attributesHide child attributes
  textstring
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobject
  The buttons.
  Show child attributesHide child attributes
  buttonsarray of objects
  One to three reply buttons.
  1 to 3 items
  Show child attributesHide child attributes
  replyobject
  A reply button.
  Show child attributesHide child attributes
  idstring
  Your identifier for the button. Returned when the recipient taps it.
  1 to 256 characters
  titlestring
  Button label, up to 20 characters.
  1 to 20 characters
  listobject
  A WhatsApp list picker: one button that opens a menu of rows grouped into sections.
  Show child attributesHide child attributes
  headerobject
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestring
  Header kind.
  Possible valuestext
  textstring
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobject
  Main message text.
  Show child attributesHide child attributes
  textstring
  Body text.
  1 to 1024 characters
  footerobject
  Optional small print below the body.
  Show child attributesHide child attributes
  textstring
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobject
  The menu.
  Show child attributesHide child attributes
  buttonstring
  Label of the button that opens the list, up to 20 characters.
  1 to 20 characters
  sectionsarray of objects
  Groups of rows.
  Show child attributesHide child attributes
  titlestring
  Section heading, up to 24 characters.
  1 to 24 characters
  rowsarray of objects
  Selectable rows.
  Show child attributesHide child attributes
  idstring
  Your identifier for the row. Returned when the recipient selects it.
  1 to 200 characters
  titlestring
  Row label, up to 24 characters.
  1 to 24 characters
  descriptionstring
  Optional second line, up to 72 characters.
  Up to 72 characters
  cta_urlobject
  A WhatsApp message with a single button that opens a URL.
  Show child attributesHide child attributes
  headerobject
  Optional header shown above the body.
  Show child attributesHide child attributes
  typestring
  Header kind.
  Possible valuestext
  textstring
  Header text, up to 60 characters.
  1 to 60 characters
  bodyobject
  Main message text.
  Show child attributesHide child attributes
  textstring
  Body text.
  1 to 1024 characters
  footerobject
  Optional small print below the body.
  Show child attributesHide child attributes
  textstring
  Footer text, up to 60 characters.
  1 to 60 characters
  actionobject
  The link button.
  Show child attributesHide child attributes
  parametersobject
  Show child attributesHide child attributes
  display_textstring
  Button label, up to 20 characters.
  1 to 20 characters
  urlstring
  URL opened when the button is tapped.
  locationobject
  A map pin. Supported on WhatsApp and Telegram.
  Show child attributesHide child attributes
  latitudenumber
  Latitude in decimal degrees.
  -90 to 90
  longitudenumber
  Longitude in decimal degrees.
  -180 to 180
  namestring
  Name of the place.
  Up to 255 characters
  addressstring
  Address of the place.
  Up to 1024 characters
  contactsarray of objects
  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
  nameobject
  Contact name.
  Show child attributesHide child attributes
  formatted_namestring
  Full display name.
  first_namestring
  Given name.
  last_namestring
  Family name.
  phonesarray of objects
  Phone numbers.
  Show child attributesHide child attributes
  phonestring
  Phone number in E.164 format.
  typestring
  Label such as CELL, WORK or HOME.
  pollobject
  A Telegram poll.
  Show child attributesHide child attributes
  questionstring
  Poll question, up to 300 characters.
  1 to 300 characters
  optionsarray of strings
  Two to ten answer options of up to 100 characters each.
  2 to 10 items
  statusstring
  Delivery status. Outbound: queued, sending, sent, delivered, read or failed. Inbound: received.
  Possible valuesqueuedsendingsentdeliveredreadfailedreceived
  errorobject or null
  Why the message failed. null unless status is failed.
  Show child attributesHide child attributes
  codestring
  Failure reason. provider_error when the channel provider rejected or could not deliver the message.
  messagestring
  Human-readable explanation.
  provider_codestring or null
  Error code returned by the channel provider. null when the provider gave none.
  referencestring or null
  Your own identifier, as supplied when sending.
  Up to 255 characters
  metadataobject
  Key-value pairs supplied when sending. Empty object if none.
  billingobject
  How the message was paid for.
  Show child attributesHide child attributes
  sourcestring
  package: one package credit was consumed. wallet: amount_micros was debited from the wallet. none: not billed (test mode and inbound messages).
  Possible valuespackagewalletnone
  amount_microsinteger
  Amount debited from the wallet in micro-USD. 0 unless source is wallet.
  package_grant_idstring or null
  Package the credit came from, when source is package.
  refundedboolean
  Whether the charge was returned because the message failed.
  senderobject or null
  Inbound messages: what the channel reported about the sender. null on outbound messages and when the channel reported nothing.
  Show child attributesHide child attributes
  namestring or null
  Display name the sender has on the channel (the WhatsApp profile name, the Telegram first and last name).
  usernamestring or null
  Handle on the channel, where the channel has one (Telegram, Instagram).
  contact_idstring or null
  Inbound messages: the contact that had the sender's identifier when the message arrived (ct_…), or null when there is none. Always null on outbound messages.
  created_attimestamp
  When the message was accepted or received.
  updated_attimestamp
  When the message last changed: usually its latest status change. Filter on it with updated_after.
  sent_atstring or null
  When the provider accepted the message.
  delivered_atstring or null
  When the message reached the recipient device.
  read_atstring or null
  When the recipient read the message, on channels that report it.
  failed_atstring or null
  When the message failed.
  Channel · show attributes · hide attributes
  idstring
  Unique identifier, prefixed ch_. Sandbox channels use ch_test_<type>.
  objectstring
  Always channel.
  Value: channel
  modestring
  test for the built-in sandbox channels, live for connected channels.
  Possible valueslivetest
  typestring
  Channel type.
  Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
  namestring
  Display name you chose.
  identifierstring
  Sender identity on the channel: phone number, bot username, sender ID, page ID or account ID. Always sandbox for the built-in sandbox channels.
  statusstring
  suspended channels cannot send.
  Possible valuesactivesuspended
  connection_statusstring
  State of the link to the provider. Messages can be sent only while connected.
  Possible valuespendingconnectedreconnectingdisconnectedblocked
  capabilitiesarray of strings
  Message types the channel accepts as type when sending.
  created_attimestamp
  When the channel was created.
  Balance · show attributes · hide attributes
  objectstring
  Always balance.
  Value: balance
  currencystring
  Always USD.
  Value: USD
  wallet_microsinteger
  Wallet balance in micro-USD (1 USD = 1,000,000).
  packagesarray of objects
  Active packages with credits remaining, earliest expiry first.
  Show child attributesHide child attributes
  idstring
  Unique identifier, prefixed grant_.
  namestring
  Package name.
  quotainteger
  Messages included.
  remaininginteger
  Messages left.
  channel_typesarray of strings or null
  Channel types the credits apply to. null means every channel type.
  expires_attimestamp
  When unused credits expire.
  credits_remaininginteger
  Sum of remaining across packages.
  Package · show attributes · hide attributes
  idstring
  Unique identifier, prefixed grant_.
  namestring
  Package name.
  quotainteger
  Messages included.
  remaininginteger
  Messages left.
  channel_typesarray of strings or null
  Channel types the credits apply to. null means every channel type.
  expires_attimestamp
  When unused credits expire.
  Webhook endpoint · show attributes · hide attributes
  idstring
  Unique identifier, prefixed we_.
  objectstring
  Always webhook_endpoint.
  Value: webhook_endpoint
  modestring
  Mode of the API key that created the endpoint. The endpoint receives events of this mode only.
  Possible valueslivetest
  urlstring
  HTTPS URL that receives the events.
  descriptionstring or null
  Your note about the endpoint.
  eventsarray of strings
  Subscribed event types. ["*"] means all.
  Possible valuesmessage.sentmessage.deliveredmessage.readmessage.failedmessage.receivedchannel.connectedchannel.disconnectedbalance.lowpackage.exhaustedpackage.expiringcampaign.startedcampaign.pausedcampaign.completedcampaign.failed*
  statusstring
  disabled endpoints receive nothing. An endpoint is disabled automatically after 50 consecutive failed deliveries.
  Possible valuesactivedisabled
  filtersobject
  Server-side filters. An event is delivered only when it matches every filter that is set; events that do not carry the filtered property (for example balance.low) always pass.
  Show child attributesHide child attributes
  channel_idstring
  Only events about this channel: messages on it, and its own channel.* events.
  directionstring
  Only message events of this direction.
  Possible valuesoutboundinbound
  metadataobject
  Key-value pairs supplied by whoever created the endpoint, for its own bookkeeping. Empty object if none.
  sourcestring or null
  The tool that owns the endpoint (zapier, n8n, make…), or null for an endpoint created by hand. An endpoint with a source is removed automatically after 30 days of uninterrupted failures.
  created_byobject or null
  Who created the endpoint. null for endpoints older than this field.
  Show child attributesHide child attributes
  typestring
  A console user or an API key.
  Possible valuesuserapi_key
  idstring
  ID of that user or key.
  has_verification_tokenboolean
  Whether deliveries carry the OmniMessage-Verification-Token header. The token itself is never returned.
  secretstring
  Signing secret, prefixed whsec_. Returned only when the endpoint is created and when the secret is rolled.
  created_attimestamp
  When the endpoint was created.
  Campaign · show attributes · hide attributes
  idstring
  Unique identifier, prefixed cmp_.
  objectstring
  Always campaign.
  Value: campaign
  modestring
  Mode of the API key that created the campaign. Test-mode campaigns run against the sandbox and are free.
  Possible valueslivetest
  namestring
  Name of the campaign.
  channel_idstring
  Channel the campaign sends on.
  channel_typestring
  Type of that channel.
  Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
  statusstring
  draft until launched; scheduled while waiting for schedule.send_at; queued while the audience snapshot is taken; sending; paused; then completed, cancelled or failed.
  Possible valuesdraftscheduledqueuedsendingpausedcompletedcancelledfailed
  pause_reasonstring or null
  Why the campaign is paused. insufficient_balance means the funds ran out: top up, then resume.
  Possible valuesuseradmininsufficient_balancechannel_unavailablenull
  failure_reasonstring or null
  Why the campaign failed.
  audienceobject
  Who the campaign is sent to.
  Segment · show attributes · hide attributes
  typestring
  Value: segment
  segment_idstring
  Segment ID. The rules are evaluated when sending starts.
  List · show attributes · hide attributes
  typestring
  Value: list
  list_idstring
  Contact list ID.
  Tags · show attributes · hide attributes
  typestring
  Value: tags
  tagsarray of strings
  Contacts carrying these tags.
  1 to 20 items
  matchstring
  Whether a contact needs one of the tags or all of them.
  Possible valuesanyall
  Pasted recipients · show attributes · hide attributes
  typestring
  Value: adhoc
  countinteger
  Number of recipients supplied with the campaign.
  save_as_contactsboolean
  Whether the recipients are saved as contacts when the campaign starts.
  messageobject
  What is sent: type and the content object under the key named by type, exactly as in POST /v1/messages. Strings may contain merge tags such as {{first_name}}, {{last_name}}, {{full_name}}, {{phone}}, {{email}}, {{locale}} and {{attributes.<key>}}; each recipient gets their own value. Unknown tags are rejected when the campaign is saved.
  Show child attributesHide child attributes
  typestring
  Message type. Must be one of the capabilities of the channel. Live WhatsApp campaigns must use template.
  merge_fallbacksobject
  Value used for a merge tag when a recipient has none.
  require_opt_inboolean
  When true, only contacts whose consent for the channel type is opted_in are messaged; the others are skipped as no_consent.
  consent_declaredboolean
  Whether you declared that the recipients agreed to be contacted. Required to launch.
  scheduleobject
  When the campaign sends.
  Show child attributesHide child attributes
  send_atstring or null
  When sending starts. null starts as soon as the campaign is launched.
  timezonestring
  IANA time zone of send_window. Defaults to the time zone of the account.
  send_windowobject or null
  Local-time window outside which nothing is sent (quiet hours). A window whose end is not after its start runs overnight.
  Show child attributesHide child attributes
  startstring
  Start, HH:MM.
  endstring
  End, HH:MM.
  recipient_timezoneboolean
  Apply send_window in the time zone of each contact that has one, instead of timezone.
  throttle_per_secondinteger
  Most messages per second the campaign sends.
  1 to 100
  countersobject
  Progress. total is fixed when the audience snapshot is complete; queued + sent + failed + skipped + cancelled equals total.
  Show child attributesHide child attributes
  totalinteger
  Recipients in the snapshot.
  queuedinteger
  Recipients not sent to yet.
  sentinteger
  Messages accepted and not failed. Includes delivered and read.
  deliveredinteger
  Messages delivered. Includes read.
  readinteger
  Messages read.
  failedinteger
  Messages rejected or failed.
  skippedinteger
  Recipients that were never sent to.
  cancelledinteger
  Recipients left unsent when the campaign was cancelled.
  skip_reasonsobject
  Skipped recipients by reason.
  costobject
  Gateway fee of the campaign. Fees of the channel provider (for example Meta conversation fees) are billed by the provider and are not included.
  Show child attributesHide child attributes
  currencystring
  Always USD.
  Value: USD
  estimated_wallet_microsinteger or null
  Estimate made at launch of what the wallet would be charged, in micro-USD. null before launch.
  estimated_creditsinteger or null
  Estimate made at launch of the package credits that would be used.
  wallet_microsinteger
  Charged to the wallet so far, net of refunds for failed messages, in micro-USD.
  package_creditsinteger
  Package credits used so far, net of credits returned for failed messages.
  created_attimestamp
  When the campaign was created.
  launched_atstring or null
  When the campaign was launched.
  started_atstring or null
  When sending started.
  paused_atstring or null
  When the campaign was last paused.
  completed_atstring or null
  When the last recipient was processed.
  cancelled_atstring or null
  When the campaign was cancelled.

Event

{
  "id": "evt_6hJ9kL2zX5cV8bN1mQ4w",
  "object": "event",
  "type": "message.delivered",
  "mode": "live",
  "created_at": "2026-10-05T09:30:02.900Z",
  "data": {
    "object": {
      "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
    }
  }
}

The balance object#

Prepaid funds of the account: the wallet and the active message packages.

Attributes

objectstring
Always balance.
Value: balance
currencystring
Always USD.
Value: USD
wallet_microsinteger
Wallet balance in micro-USD (1 USD = 1,000,000).
packagesarray of objects
Active packages with credits remaining, earliest expiry first.
Show child attributesHide child attributes
- idstring
  Unique identifier, prefixed grant_.
- namestring
  Package name.
- quotainteger
  Messages included.
- remaininginteger
  Messages left.
- channel_typesarray of strings or null
  Channel types the credits apply to. null means every channel type.
- expires_attimestamp
  When unused credits expire.
credits_remaininginteger
Sum of remaining across packages.

Balance

{
  "object": "balance",
  "currency": "USD",
  "wallet_micros": 48250000,
  "packages": [
    {
      "id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
      "name": "100K messages",
      "quota": 100000,
      "remaining": 81234,
      "channel_types": null,
      "expires_at": "2027-10-05T00:00:00.000Z"
    }
  ],
  "credits_remaining": 81234
}

The pricing object#

Effective per-message wallet prices for the account.

Attributes

objectstring
Always pricing.
Value: pricing
currencystring
Always USD.
Value: USD
dataarray of objects
One entry per channel type.
Show child attributesHide child attributes
- channel_typestring
  Channel type.
  Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
- unit_price_microsinteger
  Price of one outbound message in micro-USD.

Pricing

{
  "object": "pricing",
  "currency": "USD",
  "data": [
    {
      "channel_type": "whatsapp",
      "unit_price_micros": 1000
    },
    {
      "channel_type": "telegram",
      "unit_price_micros": 300
    },
    {
      "channel_type": "sms",
      "unit_price_micros": 500
    },
    {
      "channel_type": "sms_otp",
      "unit_price_micros": 500
    },
    {
      "channel_type": "messenger",
      "unit_price_micros": 500
    },
    {
      "channel_type": "instagram",
      "unit_price_micros": 500
    },
    {
      "channel_type": "tiktok",
      "unit_price_micros": 500
    }
  ]
}

The usage object#

Outbound message volume and spend for a date range.

Attributes

objectstring
Always usage.
Value: usage
fromdate
First day of the range (UTC, inclusive).
todate
Last day of the range (UTC, inclusive).
group_bystring
The grouping that was applied.
Possible valuesdaychannel_type
dataarray of objects
Usage rows.
Show child attributesHide child attributes
- periodstring or null
  UTC day the row covers. null when group_by is channel_type. Days and channel types without usage have no row.
- channel_typestring
  Channel type the row covers.
  Possible valueswhatsapptelegramsmssms_otpmessengerinstagramtiktok
- messagesinteger
  Outbound messages accepted.
- package_creditsinteger
  Messages paid with package credits.
- wallet_microsinteger
  Amount debited from the wallet, in micro-USD.
- failedinteger
  Messages that ended failed.
- refunded_microsinteger
  Part of wallet_micros returned to the wallet because the message failed, in micro-USD. Net wallet spend is wallet_micros - refunded_micros. Package credits returned for failed messages are already deducted from package_credits.
totalsobject
Sums across data.
Show child attributesHide child attributes
- messagesinteger
  Outbound messages accepted.
- package_creditsinteger
  Messages paid with package credits.
- wallet_microsinteger
  Amount debited from the wallet, in micro-USD.
- failedinteger
  Messages that ended failed.
- refunded_microsinteger
  Part of wallet_micros returned to the wallet because the message failed, in micro-USD. Net wallet spend is wallet_micros - refunded_micros. Package credits returned for failed messages are already deducted from package_credits.

Usage

{
  "object": "usage",
  "from": "2026-10-01",
  "to": "2026-10-05",
  "group_by": "day",
  "data": [
    {
      "period": "2026-10-01",
      "channel_type": "whatsapp",
      "messages": 1200,
      "package_credits": 1000,
      "wallet_micros": 200000,
      "failed": 12,
      "refunded_micros": 2000
    },
    {
      "period": "2026-10-01",
      "channel_type": "telegram",
      "messages": 310,
      "package_credits": 310,
      "wallet_micros": 0,
      "failed": 0,
      "refunded_micros": 0
    },
    {
      "period": "2026-10-02",
      "channel_type": "whatsapp",
      "messages": 980,
      "package_credits": 980,
      "wallet_micros": 0,
      "failed": 4,
      "refunded_micros": 0
    }
  ],
  "totals": {
    "messages": 2490,
    "package_credits": 2290,
    "wallet_micros": 200000,
    "failed": 16,
    "refunded_micros": 2000
  }
}

The account object#

The account and API key behind the current request.

Attributes

objectstring
Always account.
Value: account
idstring
Unique identifier, prefixed acc_.
namestring
Account name.
modestring
Mode of the API key used for the request.
Possible valueslivetest
api_keyobject
The API key used for the request. The secret is never returned.
Show child attributesHide child attributes
- idstring
  Unique identifier, prefixed key_.
- namestring
  Key name set in the console.
- scopesarray of strings
  Scopes granted to the key.
  Possible valuesmessages:writemessages:readchannels:readchannels:writewebhooks:readwebhooks:writebilling:readcontacts:readcontacts:writecampaigns:readcampaigns:writeintegrations:readintegrations:writeevents:readevents:write
capabilitiesarray of strings
Features of the API this account can use, for example automation_events. Clients treat a missing entry (or a missing field) as "not available"; new entries appear over time.

Account

{
  "object": "account",
  "id": "acc_8nM3bV6cX9zL2kJ5hG1f",
  "name": "Acme Logistics",
  "mode": "live",
  "api_key": {
    "id": "key_1qW4eR7tY0uI3oP6aS9d",
    "name": "Production backend",
    "scopes": [
      "messages:write",
      "messages:read",
      "channels:read"
    ]
  },
  "capabilities": [
    "automation_events",
    "webhook_filters",
    "test_inbound",
    "events_feed"
  ]
}

The WhatsApp template object#

A message template registered on the WhatsApp Business Account of a channel.

Attributes

idstring
Template ID assigned by WhatsApp.
namestring
Template name. Use it as template.name when sending.
languagestring
Language code. Use it as template.language.code when sending.
categorystring
WhatsApp template category, for example UTILITY, MARKETING or AUTHENTICATION.
statusstring
Review status at WhatsApp, for example APPROVED, PENDING or REJECTED. Only approved templates can be sent.
componentsarray of objects
Template structure as defined in WhatsApp Manager.
variablesobject
What a send has to fill in, read from components: one entry per placeholder, in the order the parameters are sent. Lets a form show one labelled field per variable.
Show child attributesHide child attributes
- headerarray of objects
  Placeholders of a text header.
  Show child attributesHide child attributes
  keystring
  The placeholder as written between the braces: a position (1) or, for named parameters, a name.
  examplestring or null
  The example value the template was submitted with, when WhatsApp reports one.
- bodyarray of objects
  Placeholders of the body.
  Show child attributesHide child attributes
  keystring
  The placeholder as written between the braces: a position (1) or, for named parameters, a name.
  examplestring or null
  The example value the template was submitted with, when WhatsApp reports one.
- buttonsarray of objects
  Buttons that take a value: dynamic URLs and copy-code buttons.
  Show child attributesHide child attributes
  indexinteger
  Position of the button in the template, from 0: the index of the button component when sending.
  typestring
  Button type in lower case, for example url or copy_code.
  variablesarray of objects
  Values the button takes.
  Show child attributesHide child attributes
  keystring
  The placeholder as written between the braces: a position (1) or, for named parameters, a name.
  examplestring or null
  The example value the template was submitted with, when WhatsApp reports one.
- countinteger
  Total number of values.

WhatsApp template

{
  "id": "1203948571029384",
  "name": "order_shipped",
  "language": "en",
  "category": "UTILITY",
  "status": "APPROVED",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} has shipped."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Track order",
          "url": "https://example.com/track/{{1}}"
        }
      ]
    }
  ],
  "variables": {
    "header": [],
    "body": [
      {
        "key": "1",
        "example": null
      },
      {
        "key": "2",
        "example": null
      }
    ],
    "buttons": [
      {
        "index": 0,
        "type": "url",
        "variables": [
          {
            "key": "1",
            "example": null
          }
        ]
      }
    ],
    "count": 3
  }
}

The batch result object#

Per-item outcome of a batch send.

Attributes

objectstring
Always batch.
Value: batch
dataarray of objects
One entry per submitted message, in request order.
Show child attributesHide child attributes
- indexinteger
  Zero-based position of the message in the request.
- statusinteger
  HTTP status the message would have received from POST /v1/messages.
- messageobject
  Present when the item was accepted (status 202).
  See the message object
- errorobject
  Present when the item was rejected.
  Show child attributesHide child attributes
  typestring
  Error category. Maps one-to-one to the HTTP status class of the response.
  Possible valuesinvalid_request_errorauthentication_errorbilling_errorpermission_errornot_found_errorconflict_errorchannel_errorrate_limit_errorapi_error
  codestring
  Stable machine-readable code. Branch on this, not on message.
  messagestring
  Human-readable explanation. May change; do not parse.
  paramstring
  Path of the request field the error relates to, for example text.body.
  detailsarray of objects
  Individual validation failures, when there are several.
  Show child attributesHide child attributes
  paramstring
  Field path.
  codestring
  Validation failure code, for example missing_field or invalid.
  messagestring
  Explanation.
  request_idstring
  ID of the request, also sent as X-Request-Id. Quote it when contacting support.
  doc_urlstring
  Link to the documentation for code.
acceptedinteger
Number of accepted messages.
rejectedinteger
Number of rejected messages.

Batch result

{
  "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
}

The error response object#

Body of every non-2xx response.

Attributes

errorobject
Details of a failed request.
Show child attributesHide child attributes
- typestring
  Error category. Maps one-to-one to the HTTP status class of the response.
  Possible valuesinvalid_request_errorauthentication_errorbilling_errorpermission_errornot_found_errorconflict_errorchannel_errorrate_limit_errorapi_error
- codestring
  Stable machine-readable code. Branch on this, not on message.
- messagestring
  Human-readable explanation. May change; do not parse.
- paramstring
  Path of the request field the error relates to, for example text.body.
- detailsarray of objects
  Individual validation failures, when there are several.
  Show child attributesHide child attributes
  paramstring
  Field path.
  codestring
  Validation failure code, for example missing_field or invalid.
  messagestring
  Explanation.
- request_idstring
  ID of the request, also sent as X-Request-Id. Quote it when contacting support.
- doc_urlstring
  Link to the documentation for code.

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "text.body is required.",
    "param": "text.body",
    "details": [
      {
        "param": "text.body",
        "code": "missing_field",
        "message": "Required"
      }
    ],
    "request_id": "req_0aB3cD6eF9gH2iJ5kL8m",
    "doc_url": "https://omnimessage.co/docs/errors#parameter_missing"
  }
}