Message format

The one grammar every endpoint uses to describe a message - text, template, interactive and media.

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	Reply buttons, links, flows, payment requests, carousels	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

content.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

content.template_name · string · required

The template name, as listed by GET /templates.

content.language · string · required

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

content.body · 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.

content.header · 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.

content.buttons · object

The value of each button that needs one, by its index (from 0, as listed by GET /templates): { "0": "A-1042", "1": "SAVE20" }. The end of a dynamic link, the coupon of a copy-code button, or the payload of a quick reply.

content.code · string

For an authentication template only: the one-time code (up to 15 characters). Shortext puts it in the body and in the code button.

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

The billing category is the one Meta approved for the template. 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

content.type · string · required

button (reply buttons), cta_url (a button that opens a link), flow, payment or carousel. Their action is described in WhatsApp message types.

content.body · string · required

The text of the message.

content.action · array | object · required

For button: a list of 1 to 3 buttons { "id", "title" } (title up to 20 characters). For cta_url: { "parameters": { "display_text", "url" } }. For the other types, see WhatsApp message types.

content.header · object

{ "type": "text" | "image" | "video" | "document", "value": "text or URL", "filename": "for documents" }. A text header is limited to 60 characters; cta_url accepts a text or an image header.

content.footer · string

Up to 60 characters.

Reply buttons

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

See what they look like on WhatsApp in WhatsApp message types.

Media

content.media_type · string · required

image, video, document or audio.

content.media_url · string · required

A public URL Shortext can download the file from.

content.caption · string

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

content.filename · string

The file name shown for a document.

content.mime · 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.