Enviar mensaje, respuesta rápida o plantilla

Endpoint · POST /conversation/actions

Envía un mensaje. Cada acción manda un solo tipo de contenido: texto, media, una respuesta rápida o una plantilla. Un texto, media o respuesta rápida puede además llevar una plantilla para cuando la ventana de 24h esté cerrada (ver abajo).

Texto
Media
Respuesta rápida
Plantilla

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

Texto plano, hasta 4096 caracteres.

{
  "type": "send_message",
  "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
  "body": "Tu comprobante 📄",
  // Solo si la visión no puede transcribir el archivo (ver abajo).
  "transcription": "Comprobante de pago por $500 del 12 de marzo"
}

El file_uuid viene del flujo de Subir multimedia. El body es un caption opcional; el audio no admite caption. La transcription es obligatoria cuando la visión no puede transcribir el archivo (tipo no soportado, o por encima del tope de tamaño que le corresponde); la respuesta de /files/confirm lo anticipa con requires_transcription. Si falta en ese caso, la acción falla con TRANSCRIPTION_REQUIRED.

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

Identifica la respuesta rápida por name (sin distinguir mayúsculas).

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

language es obligatorio (formato Meta lower_UPPER, ej. es_MX). Para plantillas con header de media, ver Subir multimedia.

Plantilla con la ventana cerrada. Un send_message de texto, media o respuesta rápida puede incluir además un template opcional: si al ejecutarse la ventana de 24h está cerrada, se envía la plantilla en vez del primario (fuera de la ventana solo se pueden enviar plantillas); si está abierta, se envía el primario. Sin template, un primario con la ventana cerrada falla con WINDOW_CLOSED.

Combinaciones válidas:

Combinación	Campos	Qué se envía
Texto	`body`	El texto (requiere ventana abierta)
Media	`file_uuid` + `body` opcional (+ `transcription` si el archivo no es auto-transcribible)	La media con caption (requiere ventana abierta)
Respuesta rápida	`quick_reply`	La respuesta rápida (requiere ventana abierta)
Plantilla	`template`	La plantilla (también con la ventana cerrada)
Primario + plantilla	`body` \| `file_uuid` \| `quick_reply` + `template`	El primario si la ventana está abierta; la plantilla si está cerrada

Transcripción de media. Cuando el archivo de una media (la primaria en file_uuid o el header de una plantilla en template.header) no puede transcribirse por la visión — tipo no soportado o por encima del tope de tamaño que le corresponde — debes enviar su transcription. Si falta, esa acción falla por-acción durante la ejecución en background: TRANSCRIPTION_REQUIRED para la media primaria, TEMPLATE_HEADER_TRANSCRIPTION_MISSING para el header de plantilla (ambos 422; ver Errores).

Qué tipos se transcriben solos puede ampliarse por etapas. La señal autoritativa por archivo es requires_transcription en la respuesta de /files/confirm, que te evita seguir esas etapas. Los topes detrás de esa señal son de visión, distintos de los límites de subida. .doc, .ppt y .pptx no se transcriben solos a ningún tamaño.Tres consecuencias prácticas:

requires_transcription responde al momento del confirm. El gate que manda es el del envío, así que un archivo confirmado con false puede volver a exigir transcription si la disponibilidad cambia entre el confirm y el envío. Ante la duda, mándala.
Mandar transcription junto a un file_uuid nunca es un error, aunque el archivo no la necesitara: gana sobre la transcripción automática. Sin file_uuid el body se rechaza entero con INVALID_REQUEST (400), igual que si transcription viene vacía o con puros espacios. En cambio, un texto que solo queda vacío al quitarle los caracteres de control pasa el schema: el body se acepta con 202 y es esa acción la que falla con INVALID_REQUEST durante la ejecución en background.
El tope de tamaño depende del tipo de archivo: no es un único número para todos.

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

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

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

La media de cada lado es independiente: la del primario en file_uuid, la del header de la plantilla en template.header.file_uuid; la de una respuesta rápida va configurada en la respuesta rápida misma. Tanto la media primaria (transcription) como el header de la plantilla (template.header.transcription) aceptan su transcripción — obligatoria si la visión no puede transcribir ese archivo (ver la nota de arriba). En una lista, este objeto va en el array actions de un POST /conversation/actions — ver Armar una lista de acciones.

Ejemplo ejecutable

Un send_message sobre una conversación identificada por teléfono y canal. Según qué le pases cubre tres objetivos:

Mensaje o plantilla — un texto o media; si la ventana de 24 h está cerrada al ejecutarse, se envía la plantilla en su lugar (fuera de la ventana solo se pueden enviar plantillas).
Respuesta rápida o plantilla — igual, con una respuesta rápida guardada como contenido principal.
Solo plantilla — únicamente una plantilla; la única forma de escribir fuera de la ventana de 24 h. Admite parámetros (body_variables), header con media y botones (button_parameters).

Request

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "body": "Hola 👋, ¿en qué te puedo ayudar?"
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_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": "Tu comprobante 📄"
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_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": "Tu contrato 📄",
        "transcription": "Contrato de servicio (3 páginas): plan Pro mensual, renovación automática, cancelable con 30 días de aviso."
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_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_tu_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": "Flyer de la cita: consultorio 3, planta baja."
          },
          "body_variables": [
            { "index": 1, "value": "María" },
            { "index": 2, "value": "3 de agosto, 10:00" }
          ],
          "button_parameters": [
            { "subType": "url", "index": 0, "text": "cita/8f21" }
          ]
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_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": "Tu comprobante 📄",
        "template": {
          "name": "recordatorio",
          "language": "es_MX",
          "header": {
            "type": "document",
            "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
            "transcription": "Recordatorio: tu cita es el viernes a las 10:00 en el consultorio 3."
          }
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_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"
        }
      }
    ]
  }'

Respuesta

202 Accepted — el grupo se aceptó y corre en background. El resultado real por acción no viaja en la respuesta (se consulta después — ver Cómo se ejecuta).

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

string

Siempre processing: confirma que el grupo fue aceptado y está en ejecución.

integer

Cuántas acciones del array se admitieron para ejecución — no cuántas tuvieron éxito.

Introducción

Conceptos

Guías

Acciones

Enviar mensaje, respuesta rápida o plantilla

Ejemplo ejecutable

Request

Respuesta