Plantillas

Una plantilla es un mensaje preaprobado por Meta. Es el único tipo de mensaje que puedes enviar cuando la ventana de 24 horas está cerrada — es decir, cuando el contacto no te escribió en las últimas 24 horas. Mientras la ventana está abierta puedes enviar texto libre; una vez cerrada, solo una plantilla llega al cliente.

Las plantillas se crean y se aprueban en el dashboard. La API pública solo las consume para enviar — no las crea ni las edita.

Cómo se resuelve una plantilla

Identifica la plantilla por nombre

Una plantilla se identifica por su template_name — el mismo nombre que ves en el dashboard y que reportas a Meta.

Indica el idioma

El idioma es obligatorio en todo envío: agrega language en formato Meta lower_UPPER (ej. es_MX) para elegir cuál plantilla enviar.

Verifica que esté aprobada

Solo se pueden enviar plantillas en estado APPROVED. Una en PENDING o REJECTED no es enviable.

Componentes de una plantilla

Una plantilla se diseña y se aprueba en el dashboard con partes fijas y ranuras dinámicas. Al enviarla desde la API solo rellenas esas ranuras: no puedes agregar un header ni botones que la plantilla no tenga.

body_variables

Los placeholders del cuerpo ({{1}}, {{2}}, …). Array de { index, value }, index desde 1, hasta 30 variables.

header

El encabezado: texto, o media (imagen, video o documento) vía file_uuid.

button_parameters

El parámetro de un botón dinámico (ej. el sufijo de un botón URL). Hasta 3.

Es una unión por type — el tipo debe coincidir con cómo se diseñó la plantilla:

`type`	Campos	Notas
`text`	`text`	Texto del encabezado (hasta 1024 caracteres).
`image`	`file_uuid` (+ `transcription` opcional)	Imagen del header.
`video`	`file_uuid` (+ `transcription` opcional)	Video del header.
`document`	`file_uuid`, `filename` opcional (+ `transcription` opcional)	Documento (PDF, etc.).

El file_uuid viene del flujo de Subir multimedia. La transcription (hasta 4000 caracteres) es obligatoria cuando la visión no puede transcribir el archivo (MIME no soportado o mayor a 20 MB); si falta en ese caso, la acción falla con TEMPLATE_HEADER_TRANSCRIPTION_MISSING.

button_parameters

Array de { subType, index, text }, hasta 3 botones:

subType — hoy solo "url" (botón de URL dinámica).
index — la posición del botón dinámico dentro de la plantilla, desde 0.
text — el valor que se concatena a la URL base del botón (ej. el identificador de un recurso), hasta 1024 caracteres.

Al escribir la clave es subType (camelCase). El endpoint de lectura Detalle de plantilla devuelve el mismo campo como sub_type (snake_case): no copies la clave literal de la respuesta de lectura — al enviar, sub_type se ignora en silencio y la acción falla con INVALID_REQUEST.

Enviar una plantilla

Rellenas el objeto template según las ranuras que tenga. Estos son los casos más comunes:

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",
          "body_variables": [
            { "index": 1, "value": "Ana" },
            { "index": 2, "value": "10:00 AM" }
          ]
        }
      }
    ]
  }'

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": "promocion_visual",
          "language": "es_MX",
          "header": {
            "type": "image",
            "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
            "transcription": "Banner: 20% de descuento en toda la tienda hasta el domingo."
          },
          "body_variables": [
            { "index": 1, "value": "Ana" }
          ]
        }
      }
    ]
  }'

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": "envio_factura",
          "language": "es_MX",
          "header": {
            "type": "document",
            "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
            "filename": "factura-agosto.pdf",
            "transcription": "Factura de agosto: total $1,250, vence el 15 de agosto."
          },
          "body_variables": [
            { "index": 1, "value": "Ana" }
          ]
        }
      }
    ]
  }'

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": "rastreo_pedido",
          "language": "es_MX",
          "body_variables": [
            { "index": 1, "value": "Ana" }
          ],
          "button_parameters": [
            { "subType": "url", "index": 0, "text": "pedido/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",
        "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" }
          ]
        }
      }
    ]
  }'

Los nombres de las plantillas los ves en el dashboard, que es donde se aprueban. Para saber qué variables, header y botones espera una en concreto, consulta Detalle de plantilla.

Para enviar un texto o media mientras la ventana está abierta y que llegue la plantilla si está cerrada, incluye el template junto al contenido principal en el mismo send_message.

Datos de pago en las variables (marcadores)

Un marcador de pago es un token con forma ==nombre== que se sustituye por el dato de cobro real de esa conversación en el momento de enviar. En una plantilla va en el valor de una variable del cuerpo, nunca en el texto de la plantilla. Meta aprueba el cuerpo con los placeholders (Hola {{1}}, tu CLABE es {{2}} ({{3}})), no los valores: esos viajan en cada envío. Por eso el marcador se puede resolver ahí, y Meta nunca ve el token.

{
  "conversation": {
    "phone": "+525512345678",
    "channel": "ch_7A9K2M4Q"
  },
  "actions": [
    {
      "type": "send_message",
      "template": {
        "name": "datos_de_pago",
        "language": "es_MX",
        "body_variables": [
          { "index": 1, "value": "Manuel" },
          { "index": 2, "value": "==clabe_spei==" },
          { "index": 3, "value": "==clabe_bank==" }
        ]
      }
    }
  ]
}

Hola Manuel, tu CLABE es 646180110412345678 (STP)

Marcadores disponibles: clabe_spei, clabe_bank y account_national_link.

Solo funcionan en body_variables. En el encabezado de texto y en los parámetros de botón se rechazan con PAYMENT_MARKER_UNSUPPORTED_FIELD (422).El motivo es que el largo de esos campos se valida sobre el texto que envías —midiendo el marcador, no el dato que lo reemplaza—, así que una sustitución podría convertir un valor válido al guardarlo en un rechazo de Meta al entregarlo. Y el parámetro de un botón es el sufijo de una URL ya aprobada, así que un link de pago ahí produciría una URL anidada. Mueve el marcador a una variable del cuerpo.El pie de página de una plantilla no admite variables en absoluto; eso lo impone Meta.

Si la conversación todavía no tiene cuenta de cobro, se genera en ese momento — el marcador es el disparador. Por eso una campaña cuyas plantillas traigan marcadores crea una cuenta por destinatario: es lo que permite atribuir quién pagó.

El envío se bloquea entero, sin entregar nada, si el marcador no se puede resolver o su resultado no cabe: nombre mal escrito (PAYMENT_MARKER_UNKNOWN, 422), la conversación no tiene ese dato (PAYMENT_MARKER_DATA_UNAVAILABLE, 422), el cuerpo interpolado supera los 1024 caracteres de Meta (TEMPLATE_BODY_TOO_LONG, 422) o no se pudo generar la cuenta de cobro (PAYMENT_PROFILE_GENERATION_FAILED, 500). Nunca se entrega un mensaje a medias en un flujo de dinero.

Plantillas de prueba para conversaciones tester

El dashboard permite crear plantillas de prueba (status: FAKE) desde el módulo Tester sin pasar por la aprobación de Meta. Sirven para que el operador y los integradores prueben flujos contra conversaciones tester sin esperar la revisión de Meta. Reglas de envío vía API pública:

Conversación tester (is_tester: true en GET /conversation) — puedes enviar tanto plantillas APPROVED como plantillas FAKE. El envío replica el flujo real pero no toca Meta (wamid retorna "").
Conversación real (is_tester: false) — solo plantillas APPROVED. Si intentas enviar una plantilla FAKE o una plantilla con is_tester: true a una conversación real, la API responde con TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION (422).

El catálogo público de plantillas no incluye plantillas FAKE — solo las APPROVED reales. Si necesitas el nombre de una plantilla FAKE para enviarla, consulta al operador.

Introducción

Conceptos

Guías

Acciones

Cómo se resuelve una plantilla

Componentes de una plantilla

body_variables

header

button_parameters

header

button_parameters

Enviar una plantilla

Datos de pago en las variables (marcadores)

Plantillas de prueba para conversaciones tester

Próximos pasos

Enviar mensajes

Conversaciones

​Cómo se resuelve una plantilla

​Componentes de una plantilla

body_variables

header

button_parameters

​header

​button_parameters

​Enviar una plantilla

​Datos de pago en las variables (marcadores)

​Plantillas de prueba para conversaciones tester

​Próximos pasos

Enviar mensajes

Conversaciones

Cómo se resuelve una plantilla

Componentes de una plantilla

header

button_parameters

Enviar una plantilla

Datos de pago en las variables (marcadores)

Plantillas de prueba para conversaciones tester

Próximos pasos