API reference

Channels

Connect and manage your own senders: WhatsApp Business numbers, Telegram bots, SMS numbers and more.

Connect a channel#

POST/v1/channelsScopechannels:write

Connects one of your own senders. The credentials are passed to the delivery layer and are never returned by the API.

The channel is returned with connection_status: "pending" and moves to connected once the provider confirms the link; subscribe to channel.connected to be notified. Requires a live API key: a test key is answered with 403 live_mode_required, because test mode uses the built-in sandbox channels instead.

For telegram the bot token is verified with Telegram while the request is handled and the bot username becomes the channel identifier; a token Telegram does not accept is 422 upstream_rejected.

Messenger, Instagram and TikTok channels are authorized by signing in with Facebook or TikTok in the console (and WhatsApp can also be connected there with Meta Embedded Signup); creating them with an API key is not available, and other values of type fail with 400 parameter_invalid.

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

typestringRequired
Channel type. Messenger, Instagram and TikTok channels are connected from the console, because they require an interactive authorization with the provider.
Possible valueswhatsapptelegramsmssms_otp
namestringRequired
Display name, up to 255 characters.
1 to 255 characters
identifierstringOptional
Sender identity: E.164 phone number for whatsapp and sms, sender ID for sms_otp. Required for these types and unique per channel type. Not needed for telegram: the bot token is verified with Telegram and the bot username becomes the identifier (a value sent here is ignored).
1 to 255 characters
credentialsobjectRequired
Provider credentials for the channel type. Passed to the delivery layer and never returned by the API.
WhatsApp credentials · show attributes · hide attributes
- wab_account_idstringRequired
  WhatsApp Business Account ID.
- phone_number_idstringRequired
  Phone number ID of the sender.
- access_tokenstringRequired
  Permanent system user access token with whatsapp_business_messaging and whatsapp_business_management permissions.
Telegram credentials · show attributes · hide attributes
- access_tokenstringRequired
  Bot token issued by BotFather.
SMS credentials · show attributes · hide attributes
- account_sidstringRequired
  Twilio account SID.
- phone_number_sidstringRequired
  SID of the Twilio phone number.
- auth_tokenstringRequired
  Twilio auth token.
SMS OTP credentials · show attributes · hide attributes
- api_keystringRequired
  API key of your OTP SMS route.

Responses

201
The channel was created. Channel 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 API key is not allowed to make this request, or it is a test key.
scope_missing ip_not_allowed account_suspended live_mode_required
409
Conflict.
channel_identifier_taken idempotency_key_in_use idempotency_key_reused
422
The provider rejected the credentials or the identifier.
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/channels

Example

curl https://api.omnimessage.co/v1/channels \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "whatsapp",
    "name": "Support line",
    "identifier": "+971800123456",
    "credentials": {
      "wab_account_id": "104857600123456",
      "phone_number_id": "209715200654321",
      "access_token": "EAAG..."
    }
  }'

Response · 201

{
  "id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "object": "channel",
  "mode": "live",
  "type": "whatsapp",
  "name": "Support line",
  "identifier": "+971800123456",
  "status": "active",
  "connection_status": "pending",
  "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"
}

List channels#

GET/v1/channelsScopechannels:read

Returns the channels of the key mode. A live key returns the channels you connected, newest first; a test key returns the built-in sandbox channels (ch_test_<type>), followed by any simulated channels created for test mode in the console.

Query parameters

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 channels.
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/channels

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

Response · 200

{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a channel#

GET/v1/channels/{id}Scopechannels:read

Returns one channel, including its connection_status and capabilities.

Path parameters

idstringRequired
Channel ID.

Responses

200
The channel. Channel 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/channels/{id}

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

Response · 200

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

Update a channel#

PATCH/v1/channels/{id}Scopechannels:write

Renames a channel. To change credentials or the identifier, delete the channel and connect it again. Sandbox channels cannot be updated.

Path parameters

idstringRequired
Channel ID.

Request body

namestringRequired
New display name.
1 to 255 characters

Responses

200
The updated channel. Channel object.
400
Invalid body, or the channel is a built-in sandbox channel (parameter_invalid, param: "id").
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
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

PATCH/v1/channels/{id}

curl -X PATCH https://api.omnimessage.co/v1/channels/ch_7Hq2mN5vB8cX1zL0pK3j \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line (UAE)"
  }'

Response · 200

{
  "id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "object": "channel",
  "mode": "live",
  "type": "whatsapp",
  "name": "Support line (UAE)",
  "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"
}

Delete a channel#

DELETE/v1/channels/{id}Scopechannels:write

Disconnects and removes a channel. Messages already sent remain retrievable. Messages still queued on the channel may fail. Sandbox channels cannot be deleted.

Path parameters

idstringRequired
Channel ID.

Responses

200
The channel was deleted.
400
The channel is a built-in sandbox channel (param: "id").
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
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

DELETE/v1/channels/{id}

curl -X DELETE https://api.omnimessage.co/v1/channels/ch_7Hq2mN5vB8cX1zL0pK3j \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "object": "channel",
  "deleted": true
}

List WhatsApp templates#

GET/v1/channels/{id}/templatesScopechannels:read

Returns the message templates registered on the WhatsApp Business Account of a channel, as reported by WhatsApp. Only templates with status APPROVED can be sent. Available for whatsapp channels only.

Path parameters

idstringRequired
Channel ID.

Responses

200
Templates of the channel.
400
The channel is not a WhatsApp channel.
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
404
The resource does not exist in this account and mode.
resource_missing
422
Unprocessable.
channel_not_connected
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

GET/v1/channels/{id}/templates

curl https://api.omnimessage.co/v1/channels/ch_7Hq2mN5vB8cX1zL0pK3j/templates \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "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
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}