Ir al contenido

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
  • HEADER acepta format TEXT, IMAGE, VIDEO, DOCUMENT o LOCATION.
  • BUTTONS acepta botones QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, OTP, FLOW, CATALOG, MPM y VOICE_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 devuelve 400 validation_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.

Ventana de terminal
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"
}
]
}
]
}'

La respuesta es 201 con la plantilla: id (tpl_…), status, category, components y rejected_reason cuando fue rechazada.

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) y GET /v1/templates/{id}, con el permiso read.
  • Editar: PATCH /v1/templates/{id} cambia components o category. Meta solo permite editar una plantilla APPROVED, REJECTED o PAUSED, 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/sync lo 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.

Ventana de terminal
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"
}
]
}
]
}
}'

Para una plantilla con encabezado de imagen, pasa la imagen por un enlace público.

Ventana de terminal
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"
}
]
}
]
}
}'

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

Ventana de terminal
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"
}
]
}
]
}
}'

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.

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.