Saltar al contenido principal

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

  1. Crea la plantilla en una WABA.
  2. Guarda su nombre, idioma, categoría y status actual.
  3. Espera la aprobación cuando se requiera revisión.
  4. Recupera o lista las plantillas para supervisar los cambios de estado.
  5. Envía únicamente una plantilla que sea válida para el caso de uso previsto y que esté en un estado listo para enviar.
  6. Edita o elimina la plantilla cuando cambie su contenido o su ciclo de vida.
La edición reemplaza el contenido existente de la plantilla. Incluye cada componente que deba permanecer tras la edición. Para las plantillas 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
Los nombres de las plantillas deben ser identificadores de aplicación estables. Usa variables únicamente en las posiciones admitidas por el componente seleccionado.

Respuesta

La respuesta confirma la creación de la plantilla y su estado actual. 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 el wabaId 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_v1
  • orders_pickup_ready_v2
  • growth_summer_offer_v3
Incrementa la versión principal (major) cuando un cambio afecte las posiciones de las variables, los tipos de componentes, los botones, la categoría o el significado del mensaje. Mantén los nombres independientes de los nombres de equipo y fechas.

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 de name 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 de whatsapp.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:
  1. Verifica la firma de cada evento whatsapp.template.reviewed.
  2. Deduplica las entregas por el id del evento.
  3. Resuelve el recurso por wabaId, name y language.
  4. Guarda tanto el evento de actualización como el status actual.
  5. Detén el enrutamiento de inmediato cuando el estado actual no sea APPROVED.
  6. Recupera la plantilla cuando falte un evento, se demore o entre en conflicto con un estado del registro más reciente.
  7. Ejecuta una conciliación programada y paginada de listados para detectar discrepancias.
No utilices Webhooks como tu único inventario ni hagas sondeos antes de cada mensaje.

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:
  1. Crea un nuevo nombre con versión para cada configuración regional obligatoria. Mantén sin cambios la versión aprobada actual.
  2. Espera hasta que cada configuración regional de destino esté en APPROVED; luego valida sus variables, archivos multimedia, botones, categoría y contenido procesado.
  3. 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.
  4. Transfiere el tráfico restante únicamente después de que la nueva versión cumpla tus criterios de despliegue.
Revierte cambiando el enrutamiento al nombre e idioma aprobados previamente. No utilices una edición de emergencia como reversión. Retira la versión previa solo después de que las colas, campañas, configuraciones, pruebas y períodos de reversión ya no hagan referencia a ella.

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 APPROVED de 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.