> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shortext.ny-corp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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.

```json theme={null}
{ "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.

```json theme={null}
{
  "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](https://docs.shortext.ny-corp.io/api-reference/guides/send-a-template.md).

## 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](https://docs.shortext.ny-corp.io/api-reference/whatsapp-messages.md).

**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](https://docs.shortext.ny-corp.io/api-reference/whatsapp-messages.md).

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

```json Reply buttons theme={null}
{
  "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" }
    ]
  }
}
```

```json Call-to-action link theme={null}
{
  "type": "interactive",
  "content": {
    "type": "cta_url",
    "body": "Invoice A-1042 is ready: 25,000 XAF.",
    "action": {
      "parameters": { "display_text": "Pay now", "url": "https://www.example.com/pay/A-1042" }
    }
  }
}
```

See what they look like on WhatsApp in [WhatsApp message types](https://docs.shortext.ny-corp.io/api-reference/whatsapp-messages.md).

## 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`.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.