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

**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** `array`

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

**content.category** `string` (default: utility)

`utility`, `marketing` or `authentication`.

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

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), `list`, `cta_url`, `quick_reply`, `carousel`, `flow` or `payment`.

**content.body** `string` *required*

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

**content.action** `object` *required*

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

**content.header** `object`

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

**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": {
      "buttons": [
        { "type": "reply", "reply": { "id": "slot_morning", "title": "Morning" } },
        { "type": "reply", "reply": { "id": "slot_evening", "title": "Evening" } }
      ]
    }
  }
}
```

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

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