Actualizado el 29/10/2026
Una plantilla de la API de WhatsApp es un mensaje aprobado previamente por Meta y es el único tipo de mensaje que se puede enviar fuera de la ventana de atención al cliente de 24 horas. Creas la plantilla por API con nombre, idioma, categoría (marketing, utilidad o autenticación) y componentes; Meta la revisa en hasta 24 horas y, si la aprueba, la envías completando las variables. La categoría define el precio, y cualquier intención promocional en el texto hace que Meta trate una plantilla de utilidad como marketing.
Esta guía muestra cómo armar, crear y enviar plantillas con payloads reales, por qué se rechazan y cómo redactar avisos que sigan siendo de utilidad.
Cuándo la plantilla es obligatoria
La Cloud API separa dos tipos de mensajes. Los mensajes libres (texto, imagen, botones, listas) solo se pueden enviar mientras la ventana de 24 horas está abierta, es decir, después de que el usuario escribió o llamó a la empresa. Fuera de ella, solo salen plantillas aprobadas.
En la práctica, las plantillas sirven para:
- avisar sobre un pedido, pago, cita o cambio en la cuenta;
- enviar un código de verificación (OTP);
- mandar ofertas y campañas a quien aceptó recibirlas;
- retomar el contacto con quien no habla contigo hace más de 24 horas.
Las tres categorías de plantilla
Toda plantilla necesita una categoría. Meta valida la elección según el contenido, y la categoría se usa en el cobro (consulta las tarifas para Brasil en precio de la API de WhatsApp en Brasil y las de otros mercados en precio de la API de WhatsApp por país). Para entender a fondo cómo decide Meta, lee categorías de plantillas de WhatsApp.
| Categoría | Para qué sirve | Ejemplos aceptados | Puntos de atención |
|---|---|---|---|
MARKETING | Difusión, ventas, retargeting, promoción de app, relación con el cliente | Cupón, carrito abandonado, renovación de suscripción con descuento, cumpleaños | También recibe plantillas con contenido mixto (aviso + promoción) o vago, como solo {{1}} |
UTILITY | Dar seguimiento a una acción o solicitud del usuario | Confirmación y seguimiento de pedido, alerta de cuenta, recordatorio de cobro, encuesta sobre una atención específica | Debe ser no promocional y específica del usuario, o esencial (seguridad, retiro de producto, cambio en la política de privacidad) |
AUTHENTICATION | Código de un solo uso para verificar identidad | «{{1}} es tu código de verificación.» | Exige botón de OTP (copiar código o autocompletar); sin URL, multimedia ni emojis; parámetros de hasta 15 caracteres |
Los códigos de verificación solo pueden ir en plantillas de autenticación. Cuando Meta detecta una plantilla de marketing o utilidad que debería ser de autenticación, avisa y cambia el estado a REJECTED el primer día del mes siguiente.
¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →
Anatomía: los componentes de una plantilla
Una plantilla tiene hasta cuatro componentes. Solo el cuerpo es obligatorio.
| Componente | Obligatorio | Límites principales |
|---|---|---|
Encabezado (HEADER) | No | Texto de hasta 60 caracteres y 1 parámetro; o multimedia (imagen, video, documento; GIF solo por la Marketing Messages API); o ubicación (solo utilidad y marketing) |
Cuerpo (BODY) | Sí | Hasta 1.024 caracteres, varios parámetros |
Pie (FOOTER) | No | Hasta 60 caracteres, solo texto |
Botones (BUTTONS) | No | Hasta 10 en total, con límites por tipo |
Los botones más usados siguen estas reglas:
| Tipo de botón | Cantidad máxima | Detalles |
|---|---|---|
QUICK_REPLY | 10 | Etiqueta de hasta 25 caracteres; el toque envía el texto como mensaje del usuario |
URL | 2 | Etiqueta de hasta 25 caracteres; URL de hasta 2.000 caracteres con 1 variable al final |
PHONE_NUMBER | 1 | Etiqueta de hasta 25 caracteres; número de hasta 20 caracteres |
COPY_CODE | 1 | Texto copiado de hasta 20 caracteres (p. ej., un cupón) |
FLOW | — | Abre un WhatsApp Flow |
Las respuestas rápidas y los demás botones deben ir agrupados (todas las respuestas rápidas juntas). Las plantillas con 4 o más botones, o con respuesta rápida mezclada con otro tipo, no se ven en WhatsApp para escritorio: se le pide al usuario que las abra en el celular. Con más de tres botones, el mensaje muestra dos y agrupa el resto en «Ver todas las opciones».
Cómo crear una plantilla por API
En la Cloud API directa, la creación es un POST al endpoint message_templates de la cuenta de WhatsApp Business (WABA). Desde el cambio de estructura del 23/09/2026, las plantillas, el cobro y los webhooks pertenecen a lo que Meta llama cuenta de mensajes, que sigue identificada por el ID de la WABA; el nuevo modelo se explica en cuenta de WhatsApp vs. cuenta de mensajes.
curl 'https://graph.facebook.com/v26.0/TU_WABA_ID/message_templates' \
-H 'Authorization: Bearer TOKEN_DE_META' \
-H 'Content-Type: application/json' \
-d '{ "name": "template_name", "language": "es", "category": "UTILITY", "components": [ { "type": "BODY", "text": "..." } ] }'En Vectalk, el cuerpo es el mismo. Cambian la URL base y el token: con un token de instancia, la WABA se resuelve automáticamente y no hace falta informar el ID en la ruta.
curl -X POST https://apis.vectalk.com.br/api/templates \
-H "Authorization: Bearer TU_TOKEN_DE_INSTANCIA" \
-H "Content-Type: application/json" \
-d '{
"name": "pedido_confirmado",
"language": "es",
"category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "TEXT", "text": "Pedido confirmado" },
{
"type": "BODY",
"text": "Hola, {{1}}. Tu pedido {{2}} fue confirmado y llegará en un plazo de {{3}} días hábiles.",
"example": { "body_text": [["Marina", "48213", "5"]] }
},
{ "type": "FOOTER", "text": "Tienda Ejemplo" },
{
"type": "BUTTONS",
"buttons": [
{ "type": "URL", "text": "Seguir pedido", "url": "https://tienda.ejemplo.com/pedidos/{{1}}", "example": ["https://tienda.ejemplo.com/pedidos/48213"] }
]
}
]
}'La respuesta trae el id, el status (en general PENDING) y la categoría. El resultado de la revisión llega por el webhook message_template_status_update, que Vectalk reenvía en el mismo formato de Meta a las URL registradas (consulta la guía de webhooks de la API de WhatsApp). Para consultarla después, usa GET /api/templates?name=pedido_confirmado.
Reglas que evitan errores ya en la creación:
- El nombre acepta solo letras minúsculas, números y guion bajo, con hasta 512 caracteres. Los nombres no son únicos: el mismo nombre puede existir en distintos idiomas, y cada idioma cuenta como una plantilla.
- Meta permite crear hasta 100 plantillas por hora en cada cuenta de mensajes.
- Una cuenta de mensajes puede tener hasta 250 plantillas si el portafolio comercial no está verificado. Con el portafolio verificado y al menos un nombre visible aprobado, el tope sube a 6.000.
- Meta no traduce nada. Cada idioma necesita su propio texto y sus propios ejemplos.
- En Meta, un encabezado multimedia exige un handle obtenido con la Resumable Upload API, y la imagen de ejemplo también pasa por la revisión.
Variables: posicionales o con nombre
El campo parameter_format define el formato. Sin él, el valor predeterminado es positional.
Posicionales: usan {{1}}, {{2}} y así sucesivamente, en secuencia. Los valores de ejemplo en la creación y los valores reales en el envío siguen el orden en que aparecen en el texto.
Con nombre: usan nombres en minúsculas con guion bajo, como {{nombre_cliente}}. El orden de los valores deja de importar, lo que reduce errores cuando el texto cambia:
{
"name": "pedido_enviado",
"language": "es",
"category": "UTILITY",
"parameter_format": "named",
"components": [
{
"type": "BODY",
"text": "¡Hola, {{nombre_cliente}}! Tu pedido {{numero_pedido}} salió a reparto con el código de seguimiento {{seguimiento}}. Te avisaremos cuando se entregue.",
"example": {
"body_text_named_params": [
{ "param_name": "nombre_cliente", "example": "Marina" },
{ "param_name": "numero_pedido", "example": "48213" },
{ "param_name": "seguimiento", "example": "BR123456789" }
]
}
}
]
}En el envío, cada parámetro con nombre lleva parameter_name:
{ "type": "text", "parameter_name": "seguimiento", "text": "BR987654321" }Todo parámetro necesita un valor de ejemplo en la creación. Sin ejemplo, la revisión no tiene cómo evaluar el texto final.
Envío de la plantilla
El envío usa el endpoint de mensajes con type: "template". Con Vectalk:
curl -X POST https://apis.vectalk.com.br/api/messages \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5584999999999",
"type": "template",
"template": {
"name": "pedido_confirmado",
"language": { "code": "es" },
"components": [
{ "type": "body", "parameters": [
{ "type": "text", "text": "Marina" },
{ "type": "text", "text": "48213" },
{ "type": "text", "text": "5" }
]},
{ "type": "button", "sub_type": "url", "index": "0", "parameters": [
{ "type": "text", "text": "48213" }
]}
]
}
}'Con un token de organización, incluye también en el cuerpo el phone_number_id del número remitente. Los errores más comunes en el envío son estos:
| Código | Significado | Qué hacer |
|---|---|---|
132000 | Cantidad de parámetros distinta a la definida en la plantilla | Revisar cuántos parámetros espera cada componente |
132001 | La plantilla no existe en el idioma indicado o no está aprobada | Revisar nombre, código de idioma y estado |
132012 | Parámetros con un formato distinto al de la plantilla | Usar el formato correcto (posicional o con nombre) |
132015 | Plantilla pausada por baja calidad | Esperar la pausa o editar el contenido |
132016 | Plantilla desactivada tras pausas repetidas | Crear una plantilla nueva con otro contenido |
Por qué se rechazan las plantillas
La revisión combina sistemas automáticos y análisis manual y tarda hasta 24 horas. Los motivos que Meta señala como más comunes son:
- Formato de las variables: llaves faltantes o mal cerradas, caracteres especiales como
#,$o%dentro de la variable, numeración fuera de secuencia ({{1}},{{2}},{{5}}). - Demasiadas variables para el largo del texto: un cuerpo corto con muchos parámetros se rechaza. Agrega texto fijo o reduce las variables.
- Variable en los extremos: el texto no puede empezar ni terminar con un parámetro.
- Solicitud de datos sensibles: número completo de tarjeta, cuenta bancaria o documento de identidad. Pedir solo los últimos dígitos está permitido.
- Contenido amenazante: amenazar al cliente con acciones legales o exposición pública.
- Infracción de la Política de Comercio: productos y servicios prohibidos en la plataforma.
- Duplicados: el mismo texto de cuerpo y pie de una plantilla ya existente (esta regla no aplica a autenticación).
Si no estás de acuerdo con el rechazo, puedes editar y reenviar o apelar en el WhatsApp Manager, con valores de ejemplo. Meta resuelve las apelaciones en hasta 24 horas. El diagnóstico completo está en plantilla rechazada en WhatsApp.
Para editar por API, Meta permite modificar plantillas con estado APPROVED, REJECTED o PAUSED. La edición reemplaza todos los componentes a la vez, y una plantilla aprobada se puede editar hasta 10 veces en 30 días o 1 vez en 24 horas. En Vectalk, la edición es un POST /api/templates/{templateId} con los nuevos componentes; la documentación de Vectalk indica que se pueden editar plantillas con estado APPROVED y REJECTED.
Cómo evitar que una plantilla de utilidad pase a marketing
Este es el problema más caro con las plantillas. Según la regla de Meta, una plantilla solo es de utilidad si cumple dos condiciones a la vez:
- Ser no promocional, sin intención persuasiva.
- Ser específica del usuario (ligada a su pedido, cuenta, servicio o transacción) o esencial (seguridad, retiro de producto, alerta de fraude, cambio en la política de privacidad).
Desde el 9 de abril de 2025, si envías una plantilla como UTILITY y Meta concluye que es marketing, se aprueba como MARKETING en lugar de rechazarse. Solo te das cuenta si miras la categoría en la respuesta o en el webhook.
Después de aprobada, la plantilla sigue siendo evaluada. Meta ejecuta un proceso recurrente que recategoriza plantillas de utilidad que deberían ser de marketing, con 1 día de aviso por el webhook template_category_update y por correo. El payload trae la categoría de la plantilla en new_category y la que debería tener en correct_category:
{
"field": "template_category_update",
"value": {
"message_template_id": 278077987957091,
"message_template_name": "recordatorio_pago",
"message_template_language": "es",
"new_category": "UTILITY",
"correct_category": "MARKETING",
"category_update_timestamp": 1746169200
}
}En la API de Meta también puedes listar las plantillas con ?fields=category,correct_category y comparar ambos campos. Cuando difieren y correct_category tiene valor, la categoría se actualiza a ese valor el primer día del mes siguiente. Tienes 60 días para pedir una revisión en el Business Support Home.
Mira la diferencia en la práctica:
| Texto | Categoría probable | Por qué |
|---|---|---|
| «Tu pedido {{1}} fue enviado con el código de seguimiento {{2}}. Te avisaremos cuando se entregue.» | Utilidad | Específico del pedido, sin promoción |
| «Tu pedido {{1}} fue enviado. ¡Aprovecha 10% en tu próxima compra!» | Marketing | Mezcla aviso con oferta |
| «Tu suscripción vence el {{1}}. Renuévala hoy con descuento.» | Marketing | Intento de renovación con incentivo |
| «Tu factura de {{1}} vence el {{2}} y se cobrará en la tarjeta terminada en {{3}}.» | Utilidad | Alerta de cuenta sin persuasión |
| «¿Cómo fue tu experiencia con nosotros?» | Marketing | Encuesta genérica, sin atención específica |
| «Hablaste con nuestro soporte sobre el pedido {{1}}. ¿Cómo fue la atención?» | Utilidad | Encuesta ligada a una interacción específica |
Una lista de control antes de enviar como utilidad:
- ¿El texto menciona algo del usuario (número de pedido, fecha, monto, número de caso)?
- ¿Alguna palabra suena a invitación a comprar, renovar o «aprovechar»?
- ¿El botón lleva a la página del pedido o de la cuenta, y no a la tienda?
- ¿El pie está libre de eslóganes o llamados comerciales?
Insistir en clasificar marketing como utilidad tiene consecuencias. Meta describe una escala de restricciones para las cuentas que lo hacen de forma recurrente:
| Nivel | Qué pasa | Duración |
|---|---|---|
| Advertencia | Aviso por escrito a los administradores de la cuenta de mensajes; los cambios de utilidad a marketing pasan a ser inmediatos, sin aviso previo | Continua |
| Límite de volumen | Volumen de mensajes de utilidad limitado en una ventana móvil de 24 horas; el excedente se rechaza | Mínimo de 7 días |
| Restricción de utilidad | Todas las plantillas de utilidad aprobadas de la cuenta pasan a marketing; se bloquean la creación de nuevas y las solicitudes de revisión de categoría | 7 días (30 en caso de reincidencia) |
| Restricción en el portafolio | Lo mismo, en todas las cuentas de mensajes del portafolio | 30 días |
Estas acciones llegan por el webhook account_update, con violation_type igual a UTILITY_TEMPLATE_ABUSE (advertencias y restricciones de utilidad) o UTILITY_TEMPLATE_ABUSE_RATE_LIMIT (límite de volumen).
Calidad y pausa de plantillas
Cada plantilla aprobada recibe una calificación basada en uso, comentarios y participación: GREEN (alta), YELLOW (media), RED (baja) o UNKNOWN (todavía sin datos). Una plantilla que llega a RED se pausa automáticamente: 3 horas la primera vez, 6 horas la segunda, y se desactiva la tercera. Mientras está pausada, la API rechaza los envíos sin cobrarlos y sin contarlos en el límite de mensajes.
Pausar las campañas que dependen de la plantilla evita una cola de errores. La pausa no afecta al número de inmediato, pero Meta advierte que enviar con frecuencia plantillas que llegan a baja calidad puede terminar afectando al número. El cuidado con volumen y público en envíos grandes por la API está en el artículo sobre envío masivo con la API oficial. Si envías marketing a escala, lee también sobre la Marketing Messages API, la vía dedicada de Meta para plantillas de marketing.
Preguntas frecuentes
¿Cuánto tarda Meta en aprobar una plantilla?
La documentación indica que la decisión sale en hasta 24 horas. Muchas plantillas se aprueban antes, pero planifica el lanzamiento contando con el plazo máximo.
¿Puedo enviar una plantilla a cualquier número?
No. Meta exige que el destinatario haya dado su consentimiento (opt-in) para recibir mensajes de tu empresa, y los envíos fuera de la ventana cuentan en el límite de mensajes del portafolio.
¿Puedo cambiar la categoría de una plantilla aprobada?
Por API, la categoría de una plantilla aprobada no se puede editar. En plantillas rechazadas, puedes editar la categoría y reenviarla. Para plantillas aprobadas como marketing que consideras de utilidad, la revisión se pide en el WhatsApp Manager.
¿Una plantilla de utilidad enviada dentro de la ventana de 24 horas es gratuita?
Ya no. Desde el 1/10/2026, Meta cobra las plantillas de utilidad enviadas dentro de la ventana de atención. El único caso en que las plantillas no se cobran es la ventana de punto de entrada gratuito, que puede quedar abierta hasta 7 días para usuarios que llegan por un anuncio de clic a WhatsApp.
En Vectalk, ¿el payload de plantilla es distinto al de Meta?
No. Los cuerpos de creación y envío son los mismos de la Cloud API. Cambian la URL base (https://apis.vectalk.com.br/api) y el token, que se genera en el panel de Vectalk.
Crea tus plantillas con Vectalk
Con Vectalk creas, listas, editas y envías plantillas con los mismos payloads de la documentación de Meta. La gestión de plantillas usa un token de instancia (uno por número), y un token de organización puede enviar mensajes desde cualquiera de tus números si incluyes el phone_number_id. El cobro funciona con una mensualidad más saldo prepago: Vectalk coloca su propia línea de crédito en tu número, cada mensaje entregado se descuenta del saldo y nunca registras una tarjeta en Meta. Crea tu cuenta en apps.vectalk.com.br/register y consulta los endpoints en docs.vectalk.com.br. Si tienes dudas, usa la página de contacto.
Fuentes oficiales consultadas el 29/10/2026: Información general de plantillas, Componentes de plantillas, Categorización de plantillas, Revisión de plantillas, Gestión de plantillas, Pausa de plantillas, Códigos de error.
Pon a funcionar el WhatsApp oficial de tu empresa
Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.