Send message, quick reply, or template

Endpoint · POST /conversation/actions

Sends a message. Each action sends one kind of content: text, media, a quick reply, or a template. A text, media, or quick reply can also carry a template for when the 24h window is closed (see below).

Text
Media
Quick reply
Template

{
  "type": "send_message",
  "body": "Hi 👋"
}

Plain text, up to 4096 characters.

{
  "type": "send_message",
  "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
  "body": "Your receipt 📄",
  // Only if vision can't transcribe the file (see below).
  "transcription": "Payment receipt for $500 dated March 12"
}

The file_uuid comes from the Upload media flow. The body is an optional caption; audio doesn’t accept a caption. The transcription is required when vision can’t transcribe the file (unsupported type, or above the size limit that applies to it); the /files/confirm response anticipates this with requires_transcription. If it’s missing in that case, the action fails with TRANSCRIPTION_REQUIRED.

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

Identifies the quick reply by name (case-insensitive).

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

language is required (Meta format lower_UPPER, e.g. es_MX). For templates with a media header, see Upload media.

Template for a closed window. A text, media, or quick reply send_message can also include an optional template: if the 24h window is closed at execution time, the template is sent instead of the primary (only templates can be sent outside the window); if it’s open, the primary is sent. Without a template, a primary with the window closed fails with WINDOW_CLOSED.

Valid combinations:

Combination	Fields	What gets sent
Text	`body`	The text (requires an open window)
Media	`file_uuid` + optional `body` (+ `transcription` if the file isn’t auto-transcribable)	The media with caption (requires an open window)
Quick reply	`quick_reply`	The quick reply (requires an open window)
Template	`template`	The template (also with the window closed)
Primary + template	`body` \| `file_uuid` \| `quick_reply` + `template`	The primary if the window is open; the template if it’s closed

Media transcription. When a media file (the primary in file_uuid or a template header in template.header) can’t be transcribed by vision — unsupported type or above the size limit that applies to it — you must send its transcription. If it’s missing, that action fails per-action during background execution: TRANSCRIPTION_REQUIRED for the primary media, TEMPLATE_HEADER_TRANSCRIPTION_MISSING for the template header (both 422; see Errors).

Which types get transcribed automatically may expand in stages. The authoritative per-file signal is requires_transcription in the /files/confirm response, which saves you from tracking those stages. The limits behind that signal are vision limits, distinct from the upload limits. .doc, .ppt and .pptx are never transcribed automatically, at any size.Three practical consequences:

requires_transcription answers as of the confirm. The gate that rules is the one at send time, so a file confirmed with false may require transcription again if availability changes between the confirm and the send. When in doubt, send it.
Sending transcription alongside a file_uuid is never an error, even when the file did not need it: it wins over automatic transcription. Without file_uuid the whole body is rejected with INVALID_REQUEST (400), and so is a transcription that is empty or whitespace-only. Text that only ends up empty once control characters are stripped does pass the schema, though: the body is accepted with 202, and it is that action that fails with INVALID_REQUEST during background execution.
The size limit depends on the file type: it is not a single number for everything.

{
  "type": "send_message",
  "body": "Hi 👋",
  "template": {
    "name": "recordatorio",
    "language": "es_MX"
  }
}

{
  "type": "send_message",
  "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
  "body": "Your receipt 📄",
  "template": {
    "name": "recordatorio",
    "language": "es_MX"
  }
}

{
  "type": "send_message",
  "quick_reply": { "name": "Bienvenida" },
  "template": {
    "name": "recordatorio",
    "language": "es_MX"
  }
}

Each side’s media is independent: the primary’s in file_uuid, the template header’s in template.header.file_uuid; a quick reply’s media is configured in the quick reply itself. Both the primary media (transcription) and the template header (template.header.transcription) accept their transcription — required if vision can’t transcribe that file (see the note above). In a list, this object goes in the actions array of a POST /conversation/actions — see Assembling an action list.

Executable example

A send_message on a conversation identified by phone and channel. Depending on what you pass, it covers three purposes:

Message or template — a text or media; if the 24h window is closed at execution time, the template is sent instead (only templates can be sent outside the window).
Quick reply or template — the same, with a saved quick reply as the primary content.
Only a template — just a template; the only way to write outside the 24h window. It supports parameters (body_variables), a media header, and buttons (button_parameters).

Request

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

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
        "body": "Your receipt 📄"
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
        "body": "Your contract 📄",
        "transcription": "Service contract (3 pages): monthly Pro plan, automatic renewal, cancelable with 30 days' notice."
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "quick_reply": { "name": "Bienvenida" }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "template": {
          "name": "confirmacion_cita",
          "language": "es_MX",
          "header": {
            "type": "image",
            "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
            "transcription": "Appointment flyer: office 3, ground floor."
          },
          "body_variables": [
            { "index": 1, "value": "María" },
            { "index": 2, "value": "August 3, 10:00" }
          ],
          "button_parameters": [
            { "subType": "url", "index": 0, "text": "appointment/8f21" }
          ]
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
        "body": "Your receipt 📄",
        "template": {
          "name": "recordatorio",
          "language": "es_MX",
          "header": {
            "type": "document",
            "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
            "transcription": "Reminder: your appointment is Friday at 10:00 in office 3."
          }
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "quick_reply": { "name": "Bienvenida" },
        "template": {
          "name": "recordatorio",
          "language": "es_MX"
        }
      }
    ]
  }'

Response

202 Accepted — the group was accepted and runs in the background. The per-action result does not travel in the response (query it later — see How it runs).

{
  "status": "processing",
  "actions_accepted": 1
}

string

Always processing: confirms the group was accepted and is running.

integer

How many actions in the array were admitted for execution — not how many succeeded.

Introduction

Concepts

Guides

Actions

Send message, quick reply, or template

Executable example

Request

Response