Skip to content
OmniMessage

Message types

Nine message types, one request body

A send request names a channel, a recipient and a type, with the content under a key named after the type. This page shows each type, the body that produces it and where it is supported.

Open the API referenceCompare channels

Support matrix

Which channel accepts which type

A channel reports what it accepts in capabilities. Sending a type that a channel does not support returns 400 unsupported_message_type and nothing is charged.

Message type support by channel type
TypeWhatsAppSMSSMS OTPTelegramMessengerInstagramTikTok
TexttextSupportedSupportedSupportedSupportedSupportedSupportedSupported
AttachmentsattachmentsSupportedSupportedNot supportedSupportedSupportedSupportedSupported
TemplatetemplateSupportedNot supportedNot supportedNot supportedNot supportedNot supportedNot supported
Reply buttonsbuttonSupportedNot supportedNot supportedSupportedSupportedSupportedSupported
ListlistSupportedNot supportedNot supportedNot supportedNot supportedNot supportedNot supported
URL buttoncta_urlSupportedNot supportedNot supportedNot supportedNot supportedNot supportedNot supported
LocationlocationSupportedNot supportedNot supportedSupportedNot supportedNot supportedNot supported
ContactscontactsSupportedNot supportedNot supportedSupportedNot supportedNot supportedNot supported
PollpollNot supportedNot supportedNot supportedSupportedNot supportedNot supportedNot supported
type: "text"

Text

Plain text, accepted by every channel type. Set preview_url to let the channel render a link preview.

body: 1 to 4,096 characters.

  • WhatsApp Business
  • SMS
  • SMS OTP
  • Telegram
  • Messenger
  • Instagram
  • TikTok
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "text",
  "text": {
    "body": "Your order #1042 has shipped. Track it at https://example.com/t/1042",
    "preview_url": true
  },
  "reference": "order-1042"
}
type: "attachments"

Attachments

One media item per message, referenced by an https URL: image, video, document, audio, voice or sticker, with an optional caption.

Exactly one item. caption: up to 1,024 characters.

  • WhatsApp Business
  • SMS
  • Telegram
  • Messenger
  • Instagram
  • TikTok
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "attachments",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/receipts/1042.jpg",
      "caption": "Your receipt for order #1042."
    }
  ]
}
type: "template"

Template

An approved WhatsApp template with variables. Templates are the only messages WhatsApp accepts outside the 24-hour customer service window.

name and language must match an approved template of the channel.

  • WhatsApp Business
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "template",
  "template": {
    "name": "order_out_for_delivery",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Layla"
          },
          {
            "type": "text",
            "text": "#1042"
          },
          {
            "type": "text",
            "text": "18:00"
          }
        ]
      }
    ]
  }
}
type: "button"

Reply buttons

A message with up to three quick replies. The ID of the tapped button comes back to your webhook in a message.received event.

1 to 3 buttons. title: up to 20 characters.

  • WhatsApp Business
  • Telegram
  • Messenger
  • Instagram
  • TikTok
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "button",
  "button": {
    "body": {
      "text": "Your table for two is booked for 19:30 tonight. Can you still make it?"
    },
    "action": {
      "buttons": [
        {
          "reply": {
            "id": "confirm",
            "title": "Confirm"
          }
        },
        {
          "reply": {
            "id": "reschedule",
            "title": "Reschedule"
          }
        },
        {
          "reply": {
            "id": "cancel",
            "title": "Cancel booking"
          }
        }
      ]
    }
  }
}
type: "list"

List

A menu that opens from a single button, with rows grouped into titled sections.

action.button: up to 20 characters.

  • WhatsApp Business
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "list",
  "list": {
    "body": {
      "text": "Which team can help you today?"
    },
    "action": {
      "button": "Choose a team",
      "sections": [
        {
          "title": "Teams",
          "rows": [
            {
              "id": "orders",
              "title": "Orders",
              "description": "Delivery, returns and refunds"
            },
            {
              "id": "billing",
              "title": "Billing",
              "description": "Invoices and payment methods"
            },
            {
              "id": "technical",
              "title": "Technical support",
              "description": "Setup and troubleshooting"
            }
          ]
        }
      ]
    }
  }
}
type: "cta_url"

URL button

A message with one button that opens a URL, for tracking pages, payments and sign-in links.

One button per message.

  • WhatsApp Business
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "cta_url",
  "cta_url": {
    "body": {
      "text": "Your parcel is on its way. Follow it in real time."
    },
    "action": {
      "parameters": {
        "display_text": "Track order",
        "url": "https://example.com/t/1042"
      }
    }
  }
}
type: "location"

Location

A pin with a name and an address that opens in the recipient’s maps app.

latitude and longitude are decimal degrees.

  • WhatsApp Business
  • Telegram
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "location",
  "location": {
    "latitude": 25.2048,
    "longitude": 55.2708,
    "name": "Pickup point",
    "address": "Sheikh Zayed Road, Dubai"
  }
}
type: "contacts"

Contacts

One or more contact cards. The array is forwarded to the channel as it is, so it uses the provider’s own contact format.

The example shows the WhatsApp contact format.

  • WhatsApp Business
  • Telegram
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "Support desk",
        "first_name": "Support"
      },
      "phones": [
        {
          "phone": "+971800123456",
          "type": "WORK"
        }
      ]
    }
  ]
}
type: "poll"

Poll

A native Telegram poll with a question and a set of options.

Telegram only.

  • Telegram
POST /v1/messages
{
  "channel": "ch_4Tn8rW2yK6dF9sA1mQ5v",
  "to": "584201337",
  "type": "poll",
  "poll": {
    "question": "When should we deliver your order?",
    "options": [
      "Morning, 09:00 to 12:00",
      "Afternoon, 12:00 to 17:00",
      "Evening, 17:00 to 21:00"
    ]
  }
}

Try every type in the sandbox

Every account has a sandbox channel for each channel type. Send any type it supports with a test key, and nothing is delivered or billed.

Get an API keyRead the docs