Plantillas
Plantillas: crear y enviar
Crea plantillas de WhatsApp con POST /v1/templates, sigue la aprobación de Meta y envía con type template, con variables, encabezado multimedia y botón de URL.
Una plantilla es un mensaje con texto fijo y variables que Meta debe aprobar antes de que puedas usarla. En WhatsApp es la única forma de iniciar una conversación, o de escribir a un contacto cuando ya se cerró la ventana de 24 horas (consulta Ventanas de conversación). Dentro de la ventana puedes enviar texto libre o cualquier otro tipo.
Esta página cubre plantillas de cualquier categoría. Para códigos de verificación, consulta Plantillas de autenticación; para envíos masivos, Campañas.
POST /v1/templates crea la plantilla en la cuenta de WhatsApp de la conexión y la envía a revisión de Meta. Requiere una clave con el permiso templates. En el panel: Plantillas → Nueva plantilla.
| Campo | Regla |
|---|---|
connection_id |
Opcional con clave de conexión (mjc_…); obligatorio con clave de organización (mj_…) |
name |
Letras minúsculas, números y _ |
language |
Código de idioma de Meta, como pt_BR, en_US o es |
category |
MARKETING, UTILITY o AUTHENTICATION |
parameter_format |
Opcional: POSITIONAL ({{1}}) o NAMED |
components |
Lista con como máximo uno de cada: HEADER, BODY (con text, obligatorio), FOOTER y BUTTONS |
HEADERaceptaformatTEXT,IMAGE,VIDEO,DOCUMENToLOCATION.BUTTONSacepta botonesQUICK_REPLY,URL,PHONE_NUMBER,COPY_CODE,OTP,FLOW,CATALOG,MPMyVOICE_CALL.- Los componentes siguen el formato de creación de Meta. Las variables del texto necesitan un
example, como en el cuerpo de abajo. - Un encabezado multimedia (
IMAGE,VIDEO,DOCUMENT) exige un archivo de ejemplo:components.HEADER.example.header_handle, el identificador que devuelve la subida reanudable de Meta. Sin él la llamada devuelve400validation_failed. En el panel, Messajo hace esa subida cuando eliges el archivo.
Ejemplo: cuerpo con dos variables, pie y un botón de respuesta rápida.
curl https://api.messajo.com/v1/templates \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "name": "pedido_enviado", "language": "es", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Hola {{1}}, tu pedido {{2}} salió para entrega.", "example": { "body_text": [ [ "Ana", "12345" ] ] } }, { "type": "FOOTER", "text": "Gracias por comprar con nosotros" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Hablar con la tienda" } ] } ]}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const template = await messajo.templates.create({ connection_id: "conn_...", name: "pedido_enviado", language: "es", category: "UTILITY", components: [ { type: "BODY", text: "Hola {{1}}, tu pedido {{2}} salió para entrega.", example: { body_text: [ [ "Ana", "12345" ] ] } }, { type: "FOOTER", text: "Gracias por comprar con nosotros" }, { type: "BUTTONS", buttons: [ { type: "QUICK_REPLY", text: "Hablar con la tienda" } ] } ]});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/templates - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "name": "pedido_enviado", "language": "es", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Hola {{1}}, tu pedido {{2}} salió para entrega.", "example": { "body_text": [ [ "Ana", "12345" ] ] } }, { "type": "FOOTER", "text": "Gracias por comprar con nosotros" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Hablar con la tienda" } ] } ]}Sustituye mj_... por tu clave de API.
La respuesta es 201 con la plantilla: id (tpl_…), status, category, components y rejected_reason cuando fue rechazada.
Ciclo de vida
Sección titulada «Ciclo de vida»Una vez creada, la plantilla pasa a la revisión de Meta. Cada cambio de estado llega en el evento template.status; también puedes consultar GET /v1/templates/{id}.
| Estado | Qué significa |
|---|---|
PENDING |
En revisión. Todavía no se puede enviar. |
APPROVED |
Aprobada. Se puede enviar. |
REJECTED |
Meta la rechazó; el motivo viene en rejected_reason. Edítala y vuelve a enviarla a revisión. |
PAUSED |
Meta la pausó por baja calidad. No se envía hasta que vuelva. |
DISABLED |
Meta la desactivó. |
También existen IN_APPEAL, PENDING_DELETION, DELETED, ARCHIVED, LIMIT_EXCEEDED, LOCKED, FLAGGED y REINSTATED, que llegan de Meta tal cual.
- Listar y consultar:
GET /v1/templates(con filtros y paginación) yGET /v1/templates/{id}, con el permisoread. - Editar:
PATCH /v1/templates/{id}cambiacomponentsocategory. Meta solo permite editar una plantillaAPPROVED,REJECTEDoPAUSED, y una plantilla aprobada no cambia de categoría. - Eliminar:
DELETE /v1/templates/{id}la elimina en Meta y en Messajo. - Sincronizar: Messajo vuelve a leer las plantillas de Meta cada día.
POST /v1/templates/synclo hace ahora; la plantilla que desapareció de Meta queda marcada como eliminada.
POST /v1/messages con type: "template":
| Campo | Regla |
|---|---|
template.name |
Nombre de la plantilla, de 1 a 512 caracteres |
template.language |
Código de idioma, como es |
template.components |
Opcional. Valores de las variables, en el formato de envío de Meta: Messajo los pasa tal como los escribes |
Los campos comunes (to, reply_to, typing…) están en Campos comunes. Una plantilla no depende de la ventana de 24 horas: sale en cualquier momento.
Variables del cuerpo
Sección titulada «Variables del cuerpo»curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "pedido_enviado", "language": "es", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Ana" }, { "type": "text", "text": "12345" } ] } ] }}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "template", template: { name: "pedido_enviado", language: "es", components: [ { type: "body", parameters: [ { type: "text", text: "Ana" }, { type: "text", text: "12345" } ] } ] }});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "pedido_enviado", "language": "es", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Ana" }, { "type": "text", "text": "12345" } ] } ] }}Sustituye mj_... por tu clave de API.
Encabezado de imagen
Sección titulada «Encabezado de imagen»Para una plantilla con encabezado de imagen, pasa la imagen por un enlace público.
curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "promo_de_la_semana", "language": "es", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://ejemplo.com/promo.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Ana" } ] } ] }}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "template", template: { name: "promo_de_la_semana", language: "es", components: [ { type: "header", parameters: [ { type: "image", image: { link: "https://ejemplo.com/promo.jpg" } } ] }, { type: "body", parameters: [ { type: "text", text: "Ana" } ] } ] }});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "promo_de_la_semana", "language": "es", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://ejemplo.com/promo.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Ana" } ] } ] }}Sustituye mj_... por tu clave de API.
Botón de URL con sufijo dinámico
Sección titulada «Botón de URL con sufijo dinámico»Cuando la URL del botón termina en {{1}}, envía el sufijo en un componente button con sub_type: "url". index es la posición del botón, desde "0".
curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "seguir_pedido", "language": "es", "components": [ { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "12345" } ] } ] }}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "template", template: { name: "seguir_pedido", language: "es", components: [ { type: "button", sub_type: "url", index: "0", parameters: [ { type: "text", text: "12345" } ] } ] }});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "seguir_pedido", "language": "es", "components": [ { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "12345" } ] } ] }}Sustituye mj_... por tu clave de API.
La respuesta es la misma que la del envío de texto (201, status: "queued"); consulta Respuesta.
Meta cobra cada mensaje de plantilla según su categoría. Consulta Costos de Meta.
Errores
Sección titulada «Errores»| Error | Cuándo | Qué hacer |
|---|---|---|
422 template_error |
Meta rechazó la plantilla o sus parámetros (códigos 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) | Lee details[].message: indica qué elemento falló |
404 template_not_found |
La plantilla no existe | Revisa name y language; ejecuta POST /v1/templates/sync |
422 marketing_limit_reached |
Meta limitó el marketing para este contacto (131049) | No reenvíes enseguida |
429 meta_spam_rate_limited |
Límite por spam (131048) | Nunca reenvíes |
402 meta_payment_required |
Problema de pago en la cuenta de Meta (131042) | Corrige el método de pago |
Más pasos en Fallos de envío.