Lo que la estructura del payload ya dice (límite de caracteres, tipos
aceptados, cantidad) está declarado en el schema de
Referencia de la API: el playground lo muestra
campo por campo. Esta página es para las reglas que el schema no expresa.
Límites de caracteres
El nombre acepta minúsculas, números y guion bajo, y no cambia después de
creada.
Salto de línea
Solo el mensaje acepta salto de línea. Encabezado, pie y texto del botón son de una línea:\n, \r y tabulación allí son motivo de rechazo, y lo mismo
vale para más de cuatro espacios seguidos.
En el mensaje, evita una línea en blanco al final y más de dos saltos seguidos.
Variables
Es de lejos lo que más genera rechazo.La variable no puede abrir ni cerrar el texto
2388299.
Toda variable necesita ejemplo
Sin elexample, Meta rechaza con missing expected field(s) (example), código
2388043. El ejemplo es lo que el revisor lee para entender la plantilla.
En el posicional, la numeración es secuencia y empieza en 1
El ejemplo viaja como lista, y Meta empareja cada ítem por posición. Con{{1}} y {{3}}, el tercero queda sin ejemplo, y el rechazo habla de un campo
que falta sin mencionar la numeración.
El encabezado acepta una variable
Una sola. La segunda vuelve como “The Header field can only have up to 1 variable(s)”, código2388029.
El pie no acepta variables
Meta trata el pie como texto puro: la variable allí no se sustituye y va literal al cliente.Texto corto con muchas variables se rechaza
Meta compara la cantidad de variables con el largo del texto y rechaza lo que es desproporcionado, con el código2388293. No publica la fórmula. Según nuestra
medición, con dos variables o más, cuenta tres palabras de texto por variable,
más una.
Botones
Las respuestas rápidas van todas juntas
Meta no exige que vayan primero: exige que los botones queden en dos grupos, el de las respuestas rápidas y el de los demás. Una respuesta rápida en medio de otros tipos se rechaza.Formato de la dirección y del teléfono
La dirección necesitahttp o https. www.tutienda.com sin protocolo se
rechaza, y el error cita el índice del botón en el payload.
El teléfono va en formato internacional, con el código del país:
+5511988881234. Sin el + y sin el país, el rechazo es
(#192) ... is not a valid phone number.
Variable en el botón
El botón de enlace acepta una variable, y solo al final de la dirección:Etiquetas que Meta escribe
En catálogo, multiproducto, producto único, checkout, pedido y en el código de autenticación, el texto del botón es de Meta. El campotext sigue siendo
obligatorio: lo que cambia es que el valor no es tuyo. Mandar otro se rechaza
con el código 2388153, y la respuesta dice cuál era el correcto.
La app de WhatsApp traduce la etiqueta al idioma de quien recibe, así que el
valor que mandas en la creación no es lo que lee el cliente.
Carrusel
- De 2 a 10 tarjetas en el de medios. En el de producto, exactamente 2 en la creación, y hasta 10 en el envío.
- Todas las tarjetas con los mismos componentes. En consecuencia: si una tarjeta tiene texto, todas necesitan tenerlo; el conjunto de botones (tipo y orden) es igual en todas. Lo que cambia de una a otra es el texto del botón y el destino.
- En el de medios, toda tarjeta necesita medio.
- La tarjeta de producto tiene encabezado
{"format": "PRODUCT"}y un único botón, sin texto de tarjeta. Enviar dos botones o un cuerpo vuelve comocomponent of type BODY is required, código2388045, que no describe la causa.
Medios
En el encabezado y en las tarjetas, la referencia del medio es el
identificador obtenido en Enviar medios, o el
enlace público del archivo, que convertimos a identificador antes de crear
la plantilla.
El enlace tiene que abrirse para un servidor, y no solo en el navegador. Tiendas
y blogs suelen bloquear la descarga automática, y entonces Meta responde
media download failed, código 380.
La imagen de encabezado se muestra en 1.91:1, horizontal. Lo que quede
fuera de esa proporción no se rechaza: WhatsApp recorta lo que sobra para que
quepa, y el recorte es por el centro. Conviene armar el arte con esa medida, o
aceptar que los bordes desaparezcan en el teléfono del cliente.
Validez del envío
message_send_ttl_seconds tiene un rango por categoría:
El valor
-1 es un atajo de 30 días. En autenticación, la validez del envío no
puede ser menor que la del código: si el mensaje deja de entregarse antes, el
cliente pierde las dos cosas.
Cuántas plantillas caben en la cuenta
Los límites de abajo son de la cuenta, y no de la plantilla que estás creando. Por eso su rechazo confunde: no habla de nada que esté en tu payload.
El nombre es único por WABA e idioma: el mismo nombre en
pt_BR y en
en_US son dos plantillas, y las dos se aceptan. Repetir nombre e idioma en la
misma cuenta vuelve como already exists — incluso cuando la otra se eliminó
hace menos de 30 días, porque eliminar reserva el nombre por ese período.
Pasar de 100 creaciones por hora no es error de payload: es cola. Si estás
migrando un catálogo de plantillas de una vez, créalas por lotes y espera
entre ellos, en lugar de reintentar de inmediato.
Editar y eliminar
- Una plantilla aprobada acepta hasta 10 ediciones en 30 días, y una cada 24 horas. Rechazada y pausada no tienen ese tope.
- Solo aprobada, rechazada y pausada pueden editarse.
- Nombre e idioma no cambian. La categoría de una plantilla aprobada tampoco.
- La edición sustituye todos los componentes: envía el conjunto completo, porque lo que quede fuera se borra.
- Después de editar, la plantilla vuelve sola a la fila de revisión.
- Eliminar una plantilla aprobada reserva su nombre por 30 días.
Errores de Meta, y qué significa cada uno
Cuando el rechazo viene de Meta, devolvemos su mensaje original junto con el
traceId. Guarda los dos: son con los que el soporte identifica el caso.