Message format

Every endpoint that sends a message (start a conversation, reply, Shortext inbound, v1.0 send) and every message in a response or a webhook uses the same message object:

{
  "type": "text",
  "content": { "text": "Hello, how can I help?" }
}

type is one of text, template, interactive or media; content depends on it.

Type	Use it for	WhatsApp 24-hour window
`text`	Plain text	Inside only
`template`	Approved WhatsApp templates	Inside and outside
`interactive`	Buttons, lists, call-to-action links	Inside only
`media`	Images, videos, documents, audio	Inside only

Each endpoint accepts the types that make sense for it: for example a Shortext inbound message is text only.

Text

string

required

The text, up to 4,096 characters. On WhatsApp, a URL in the text is rendered as a link.

{ "type": "text", "content": { "text": "Your order A-1042 has left our warehouse." } }

Template

string

required

The template name, as listed by GET /templates.

string

required

The template language, for example fr or en_US. The template must be approved in this language.

object

The body variables, by name: { "name": "Brice", "order": "A-1042" }. For templates with numbered variables ({{1}}, {{2}}), give a list of WhatsApp parameters in order.

object

For a text header with variables: { "name": "value" }. For a media header: { "url": "https://..." } (and filename for a document). Without url, the media stored with the template is sent.

array

Parameters of dynamic buttons, in the WhatsApp Cloud API format.

string

default:"utility"

utility, marketing or authentication.

{
  "type": "template",
  "content": {
    "template_name": "order_shipped",
    "language": "fr",
    "header": { "url": "https://cdn.example.com/parcels/A-1042.jpg" },
    "body": { "name": "Brice", "order": "A-1042" }
  }
}

In v2.0, Shortext checks a template before sending it to WhatsApp and answers 1002 with an explicit message when the template does not exist on the number, is not approved in that language, or misses a variable (body.missing lists them). See Send a template.

Interactive

string

required

button (reply buttons), list, cta_url, quick_reply, carousel, flow or payment.

string

required

The text of the message, up to 1,024 characters.

object

required

The buttons, sections or link, in the WhatsApp Cloud API action format.

object

{ "type": "text" | "image" | "video" | "document" | "audio", "value": "text or URL", "filename": "for documents" }.

string

Up to 60 characters.

{
  "type": "interactive",
  "content": {
    "type": "button",
    "header": { "type": "text", "value": "Delivery" },
    "body": "When should we deliver your order?",
    "footer": "Choose a slot",
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "slot_morning", "title": "Morning" } },
        { "type": "reply", "reply": { "id": "slot_evening", "title": "Evening" } }
      ]
    }
  }
}

{
  "type": "interactive",
  "content": {
    "type": "list",
    "body": "Which product do you need help with?",
    "action": {
      "button": "See products",
      "sections": [
        {
          "title": "Phones",
          "rows": [
            { "id": "p_x1", "title": "X1", "description": "2025 model" },
            { "id": "p_x2", "title": "X2" }
          ]
        }
      ]
    }
  }
}

WhatsApp allows up to 3 reply buttons, and up to 10 sections of 10 rows in a list.

Media

string

required

image, video, document or audio.

string

required

A public URL Shortext can download the file from.

string

Up to 1,024 characters (not for audio).

string

The file name shown for a document.

string

The MIME type, for example application/pdf.

{
  "type": "media",
  "content": {
    "media_type": "document",
    "media_url": "https://cdn.example.com/invoices/A-1042.pdf",
    "filename": "Invoice A-1042.pdf",
    "caption": "Your invoice"
  }
}

Messages in responses and webhooks

Messages returned by the API and sent in message.* webhooks wrap the same object:

{
  "id": "k5Rz8pQw",
  "conversation_id": "c9Lw3nYb",
  "direction": "inbound",
  "channel": "whatsapp",
  "channel_id": "532867649916076",
  "contact": { "identifier": "237699999999", "identifier_type": "phone", "profile": { "firstname": "Brice" } },
  "message": {
    "id": "wamid.HBgM...",
    "type": "text",
    "content": { "text": "Hello, where is my order?" }
  },
  "status": "received",
  "created_at": "2026-10-24T09:12:44+00:00"
}

direction is inbound (from the contact) or outbound (from the AI agent, a member of your team or the API).
message.id is the id on the channel (WhatsApp message id; on a Shortext endpoint, your own message id).
status is received for inbound messages, then sent, delivered, read or failed for outbound ones; changes are pushed by the message.status webhook.

Get started

Formats

Integrations

Guides

Endpoints

Text

Template

Interactive

Media

Messages in responses and webhooks

​Text

​Template

​Interactive

​Media

​Messages in responses and webhooks

Text

Template

Interactive

Media

Messages in responses and webhooks