Qué es
Las plantillas de WhatsApp son estructuras de mensaje previamente aprobadas que se utilizan para iniciar o continuar conversaciones fuera de la ventana de atención al cliente. Una plantilla se identifica por su WABA, nombre e idioma. Usa esta guía para gestionar el ciclo de vida de la API y mantener estables los recursos de plantillas en producción entre equipos, versiones e idiomas.Antes de empezar
- Conecta la WABA que será propietaria de la plantilla.
- Elige la categoría de la plantilla, el idioma admitido, el nombre y los componentes.
- Prepara ejemplos representativos de variables y archivos multimedia necesarios para la revisión.
- Cumple con las políticas de Meta para contenido de autenticación, utilidad y marketing.
- Configura un endpoint de webhook que pueda recibir eventos
whatsapp.template.reviewed.
Cómo funciona
- Crea la plantilla en una WABA.
- Guarda su nombre, idioma, categoría y
statusactual. - Espera la aprobación cuando se requiera revisión.
- Recupera o lista las plantillas para supervisar los cambios de estado.
- Envía únicamente una plantilla que sea válida para el caso de uso previsto y que esté en un estado listo para enviar.
- Edita o elimina la plantilla cuando cambie su contenido o su ciclo de vida.
MARKETING, puedes añadir o actualizar el precio máximo a través de bidSpec. Al editar, omite bidSpec o envía null para conservar el precio, o envía {} para borrarlo. Consulta la guía de integración de Max Price para conocer los importes, multiplicadores por país y ejemplos completos de edición.
Solicitud
POST /whatsapp/templates
Respuesta
PENDING no significa que la plantilla ya se pueda enviar.
Definir una identidad de recurso estable
Trata cada combinación de WABA, nombre de plantilla e idioma como un único recurso. Mantén un registro de recursos con elwabaId propietario, nombre estable, código de configuración regional exacto, propósito, propietario, contrato de variables, estado actual de la API, estado de implementación y versión de sustitución.
Usa un nombre predecible como <domain>_<purpose>_v<major>:
auth_login_otp_v1orders_pickup_ready_v2growth_summer_offer_v3
Elegir la categoría antes de redactar el contenido
Elige la categoría a partir del motivo por el cual el cliente recibe el mensaje.
Si una plantilla combina información transaccional con una promoción, diséñala como de marketing o divide los propósitos en plantillas separadas.
Fijar el contrato de variables
Define las variables como un contrato de API antes de que los redactores o traductores comiencen. Para cada variable, registra su posición, significado semántico, formato, origen, ejemplo representativo y comportamiento alternativo. Por ejemplo,Order {{0}} is ready at {{1}}. puede utilizar este contrato:
Mantén estable el significado de cada posición en todas las versiones e idiomas. Crea una nueva versión si necesitas reordenar o cambiar el propósito de las variables.
Antes de enviar a revisión:
- Proporciona una muestra segura y representativa para cada variable del cuerpo o del encabezado de texto.
- Valida las URL, los formatos y los tamaños de archivo de los encabezados multimedia.
- Limita los encabezados de texto a un máximo de una variable e incluye su muestra.
- Confirma que las variables en botones de URL aparezcan solo donde la API lo permita e incluye una URL de muestra completa.
- Nunca uses credenciales, códigos de un solo uso, datos personales o contenido multimedia privado en los ejemplos de revisión.
Organizar los idiomas en una sola versión
Reutiliza el mismo nombre con versión para cada idioma en una sola publicación, pero gestiona cada par dename e language como un recurso independiente. Mantén consistentes los significados de las variables y las acciones de los botones incluso cuando cambie el orden de las palabras.
Aprueba y publica cada idioma de forma independiente. Nunca dirijas a un usuario a otro idioma solo porque esa configuración regional esté aprobada. Usa el código de idioma exacto y con distinción de mayúsculas y minúsculas en las solicitudes de creación, recuperación, edición, eliminación y envío.
Condicionar los envíos al estado de la plantilla
Usa la recuperación o webhooks dewhatsapp.template.reviewed para procesar la aprobación, rechazo, pausa, inhabilitación, archivado y otros cambios del ciclo de vida. Conserva el nombre y el idioma exactos que utilicen las solicitudes de mensajes.
Almacena el status de la API de forma independiente a tu estado de despliegue. Enruta únicamente envíos de producción hacia una plantilla cuyo estado actual sea APPROVED y cuyo estado de despliegue esté activo.
Una respuesta exitosa de creación o edición no autoriza envíos de producción.
Sincronizar el estado
Usa Webhooks para actualizaciones rápidas y las API de obtención o listado para la conciliación:- Verifica la firma de cada evento
whatsapp.template.reviewed. - Deduplica las entregas por el
iddel evento. - Resuelve el recurso por
wabaId,nameylanguage. - Guarda tanto el evento de actualización como el
statusactual. - Detén el enrutamiento de inmediato cuando el estado actual no sea
APPROVED. - Recupera la plantilla cuando falte un evento, se demore o entre en conflicto con un estado del registro más reciente.
- Ejecuta una conciliación programada y paginada de listados para detectar discrepancias.
Comportamiento de edición y eliminación
- Edita únicamente plantillas en un estado admitido por el endpoint.
- Incluye el conjunto completo de componentes deseados en una solicitud de edición.
- Eliminar por nombre borra todos los idiomas asociados a ese nombre.
- Eliminar por nombre e idioma borra únicamente esa plantilla localizada.
- Las plantillas archivadas aún pueden aparecer en los resultados de listado y recuperación.
Publicar, revertir y retirar versiones
Opta por una versión paralela en caso de cambios relevantes:- Crea un nuevo nombre con versión para cada configuración regional obligatoria. Mantén sin cambios la versión aprobada actual.
- Espera hasta que cada configuración regional de destino esté en
APPROVED; luego valida sus variables, archivos multimedia, botones, categoría y contenido procesado. - Enruta un porcentaje controlado de los envíos aptos a la nueva versión y monitoriza la entrega, la calidad, las respuestas y las actualizaciones de estado.
- Transfiere el tráfico restante únicamente después de que la nueva versión cumpla tus criterios de despliegue.
Límites y resolución de problemas
- Una solicitud de envío falla cuando la plantilla no está aprobada o sus componentes no coinciden con los parámetros del mensaje.
- Las plantillas de autenticación utilizan estructuras predefinidas restringidas.
- La categoría y el contenido de la plantilla deben cumplir las políticas de Meta.
- Revisa los detalles del rechazo antes de volver a crear el mismo contenido.
- Usa un nombre nuevo cuando una plantilla eliminada o modificada sustancialmente no pueda restablecerse de forma segura.
Lista de comprobación para la puesta en marcha
- Se han registrado el nombre, el propósito, el responsable, la categoría y la versión.
- Cada variable tiene un único significado, formato, ejemplo seguro y regla de contingencia.
- Los archivos multimedia y los botones superan las validaciones de formato, destino y ejemplos.
- Cada configuración regional requerida está en
APPROVEDde forma independiente. - La ruta de envío rechaza cualquier estado distinto a
APPROVED. - El procesamiento de Webhooks está verificado, es idempotente y está conciliado con las consultas de obtención.
- El despliegue permite restablecer una versión anterior aprobada.
- Las colas, campañas, configuraciones, pruebas y guías de procedimientos utilizan la versión prevista.
Idiomas compatibles
Selecciona el idioma exacto y el código regional de la configuración regional de la plantilla.
Ejemplos de creación de plantillas
Adapta plantillas de autenticación, marketing, utilidad, comercio, Flow y llamadas.
API de creación de plantillas
Inspecciona el esquema completo de componentes.
Webhooks de revisión de plantillas
Gestiona los cambios de estado del ciclo de vida y de revisión.

