> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages

> The four ways to send a message and which one applies based on the 24h window.

The API offers four ways to send a WhatsApp message on behalf of your business.
Which one you can use depends on the state of the conversation's
[24h window](/en/conversations).

## Which mode applies based on the window

| Mode         | Window open | Window closed          |
| ------------ | ----------- | ---------------------- |
| Text         | ✅           | ❌ `WINDOW_CLOSED`      |
| Media        | ✅           | ❌ `WINDOW_CLOSED`      |
| Quick reply  | ✅           | ❌ `WINDOW_CLOSED`      |
| **Template** | ✅           | ✅ — reopens the window |

<Tip>
  The **template** is the only message you can send with the window closed. On
  top of that, sending one reopens the window, enabling text, media, and quick
  reply again.
</Tip>

## The four ways to send

<Tabs>
  <Tab title="Text">
    Free-form text, up to 4096 characters, via `POST /conversation/messages/text`.

    ```bash theme={null}
    curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages/text" \
      -H "Authorization: Bearer sk_1to1_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "conversation": { "phone": "+5215512345678" },
        "body": "Hi 👋, how can I help you?"
      }'
    ```

    Accepts an optional `reply_to_uuid` to quote a previous message. Responds
    `201` with `message_uuid` and `wamid`.
  </Tab>

  <Tab title="Media">
    Image, video, audio, or document — same endpoint as text
    (`POST /conversation/messages/text`), passing a `file_uuid` instead of —or
    alongside— `body` as the caption.

    ```bash theme={null}
    curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages/text" \
      -H "Authorization: Bearer sk_1to1_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "conversation": { "phone": "+5215512345678" },
        "file_uuid": "7b8a...",
        "body": "Here is your receipt 📄"
      }'
    ```

    <Note>
      The `file_uuid` must belong to a file already uploaded and confirmed, from
      the same business. The message type (image, video, audio, document) is
      inferred automatically from the file. See the `/files` flow in the API
      Reference.
    </Note>

    <Warning>
      `body` (caption) is not supported with audio files. WhatsApp doesn't
      support captions on audio — combining them returns `INVALID_REQUEST` (400).
    </Warning>
  </Tab>

  <Tab title="Quick reply">
    A reply preconfigured in the dashboard, via
    `POST /conversation/messages/quick-reply`. Identified by **one** of
    `quick_reply_uuid` or `quick_reply.name` (strict XOR — sending both returns
    `400 INVALID_REQUEST`).

    ```bash theme={null}
    curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages/quick-reply" \
      -H "Authorization: Bearer sk_1to1_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "conversation": { "phone": "+5215512345678" },
        "quick_reply": { "name": "Welcome" }
      }'
    ```

    A quick reply can emit **several messages**, which is why the response is an
    array `messages` with a `message_uuid`, `wamid`, and `subtype` for each one.
  </Tab>

  <Tab title="Template">
    A template approved by Meta, via `POST /conversation/messages/template`. It
    is the only mode that works with the window closed — see
    [Templates](/en/templates) for the detail.

    ```bash theme={null}
    curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages/template" \
      -H "Authorization: Bearer sk_1to1_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "conversation": { "phone": "+5215512345678" },
        "template_name": "appointment_confirmation",
        "body_variables": [
          { "index": 1, "value": "Ana" }
        ]
      }'
    ```

    Responds `201` with `message_uuid` and `wamid`.
  </Tab>
</Tabs>

## Next steps

<CardGroup cols={2}>
  <Card title="Templates" icon="file-lines" href="/en/templates">
    Create and send templates to reopen the window.
  </Card>

  <Card title="Conversations" icon="comments" href="/en/conversations">
    Identifiers and the 24h window in detail.
  </Card>
</CardGroup>