Messages

Every WhatsApp send goes through a single action, send_message, inside the POST /conversation/actions endpoint. One action covers all four modes —text, media, quick reply, and template—; which one you can use depends on the state of the conversation’s 24h window.

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

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.

The four modes of `send_message`

Each send_message sends one kind of content: text (body), media (file_uuid), a quick reply (quick_reply), or a template (template). The first three can also carry a fallback template for when the window is closed (see below).

Text
Media
Quick reply
Template

Free-form text, up to 4096 characters.

{
  "type": "send_message",
  "body": "Hi 👋, how can I help you?"
}

Image, video, audio, or document: pass a file_uuid from a file already uploaded and confirmed, with body as an optional caption. The type is inferred from the file; audio does not allow a caption. The upload flow is in Upload media.

{
  "type": "send_message",
  "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
  "body": "Here is your receipt 📄"
}

A reply preconfigured in the dashboard, identified by name (case-insensitive). It can emit several messages.

{
  "type": "send_message",
  "quick_reply": { "name": "Welcome" }
}

A template approved by Meta — the only mode that works with the window closed. language is required (Meta format lower_UPPER, e.g. en_US). See Templates.

{
  "type": "send_message",
  "template": {
    "name": "appointment_confirmation",
    "language": "en_US",
    "body_variables": [{ "index": 1, "value": "Ana" }]
  }
}

Sending

Sending is an action within the group. Make a POST /conversation/actions with a send_message in the actions array:

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "body": "Hi 👋, how can I help you?"
      }
    ]
  }'

Responds 202: the send runs in the background. Check the result in the conversation status or the activity log. To chain several sends or other actions in a single request, see Actions.

Template fallback for a closed window

A send_message of text, media, or quick reply can also include an optional template: if the window is closed when it runs, the template is sent instead of the primary; if it’s open, the primary is sent. Without a template, a primary with the window closed fails with WINDOW_CLOSED.

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "body": "Hi 👋",
        "template": {
          "name": "reminder",
          "language": "en_US"
        }
      }
    ]
  }'

Introduction

Concepts

Guides

Actions

Which mode applies based on the window

The four modes of `send_message`

Sending

Template fallback for a closed window

Next steps

Templates

Actions

​Which mode applies based on the window

​The four modes of send_message

​Sending

​Template fallback for a closed window

​Next steps

Templates

Actions

Which mode applies based on the window

The four modes of `send_message`

Sending

Template fallback for a closed window

Next steps