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 larger than 20 MB); 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 larger than 20 MB — 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).

{
  "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

​Executable example

​Request

​Response

Executable example

Request

Response