> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Administrar plantillas de WhatsApp > Crea, versiona, revisa, publica y retira plantillas de mensaje de WhatsApp de forma segura. ## 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. Utiliza esta guía para administrar el ciclo de vida de la API y mantener estables los recursos de plantillas de producción entre equipos, versiones e idiomas. ## Antes de comenzar * Conecta la WABA que será propietaria de la plantilla. * Elige la categoría de la plantilla, el [idioma admitido](/es/api-reference/guides/whatsapp-platform/supported-whatsapp-template-languages), el nombre y los componentes. * Prepara ejemplos representativos de variables y contenido multimedia requeridos para la revisión. * Sigue 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. Almacena su nombre, idioma, categoría y `status` actual. 3. Espera la aprobación cuando se requiera revisión. 4. Consulta o lista las plantillas para observar los cambios de estado. 5. Envía únicamente una plantilla que sea válida para el caso de uso objetivo y que esté en un estado listo para envío. 6. Edita o elimina la plantilla cuando cambie su contenido o ciclo de vida. La edición reemplaza el contenido existente de la plantilla. Incluye todos los componentes que deban conservarse tras la edición. ## Solicitud `POST /whatsapp/templates` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/whatsapp/templates \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup.", "example": { "body_text": [["A-10001"]] } } ] }' ``` Los nombres de las plantillas deben ser identificadores de aplicación estables. Usa variables únicamente en las posiciones admitidas por el componente seleccionado. ## Respuesta ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "status": "PENDING", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup." } ] } ``` 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 despliegue y versión de reemplazo. Utiliza un nombre predecible como `__v`: * `auth_login_otp_v1` * `orders_pickup_ready_v2` * `growth_summer_offer_v3` Incrementa la versión principal 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 los equipos y las fechas. ## Elegir la categoría antes de redactar el contenido Elige la categoría según el motivo por el cual el cliente recibe el mensaje. | Categoría | Cuándo usarla | | - | - | | `AUTHENTICATION` | Autenticas a un usuario con un código de un solo uso para verificación, recuperación o un desafío de integridad. | | `UTILITY` | Cumples con una solicitud específica del usuario o proporcionas una actualización sobre una transacción acordada. | | `MARKETING` | Envías una oferta, promoción, invitación u otro contenido que no califique como autenticación o utilidad. | Si una plantilla combina información transaccional con una promoción, diséñala como 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 (fallback). Por ejemplo, `Order {{0}} is ready at {{1}}.` puede usar este contrato: | Posición | Significado | Formato | Ejemplo de revisión | | - | - | - | - | | `{{0}}` | `order_reference` | Cadena corta orientada al cliente | `A-10001` | | `{{1}}` | `pickup_location` | Nombre de la tienda localizado | `Central Store` | 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 encabezado de texto. * Valida las URL, los formatos y los tamaños de archivo de los encabezados multimedia. * Mantén el encabezado de texto con un máximo de una variable e incluye su muestra. * Confirma que las variables de los botones de tipo URL aparezcan únicamente donde la API lo permita e incluye una URL de muestra completa. * Nunca utilices credenciales, códigos de un solo uso, datos personales ni archivos multimedia privados en los ejemplos de revisión. ## Organizar las configuraciones regionales como un solo lanzamiento Reutiliza el mismo nombre versionado para cada configuración regional en un solo lanzamiento, pero administra cada par de `name` y `language` como un recurso independiente. Mantén la coherencia en el significado de las variables y las acciones de los botones, incluso si el orden de las palabras cambia. Aprueba y publica cada configuración regional de forma independiente. Nunca dirijas a un usuario a otro idioma solo porque esa configuración regional esté aprobada. Utiliza el código de configuración regional exacto y con distinción de mayúsculas y minúsculas en las solicitudes de creación, consulta, edición, eliminación y envío. ## Condicionar los envíos al estado de la plantilla Utiliza consultas o webhooks de `whatsapp.template.reviewed` para procesar aprobaciones, rechazos, pausas, inhabilitaciones, archivados y otros cambios en el ciclo de vida. Conserva el nombre y el idioma exactos utilizados en las solicitudes de mensajes. Almacena el `status` de la API de forma separada a tu estado de despliegue. Solo enruta envíos de producción a una plantilla cuyo estado actual sea `APPROVED` y cuyo estado de despliegue esté activo. | Estado | Acción de producción | | - | - | | `PENDING` | Bloquea los envíos mientras la revisión esté en curso. | | `APPROVED` | Permite los envíos después de que se aprueben las pruebas de contrato y el despliegue. | | `REJECTED` | Bloquea los envíos, inspecciona el motivo y corrige el contenido o el contrato. | | `PAUSED` o `DISABLED` | Detén los nuevos envíos y utiliza una alternativa aprobada cuando esté disponible. | | `IN_APPEAL` | Mantén los envíos bloqueados hasta que el estado cambie a `APPROVED`. | | `ARCHIVED` o `DELETED` | Elimina la plantilla del enrutamiento. | Una respuesta correcta de creación o edición no autoriza los envíos a producción. ## Sincronizar el estado Utiliza 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 mediante `wabaId`, `name` y `language`. 4. Almacena 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. Obtén la plantilla cuando un evento falte, se retrase o entre en conflicto con un estado del registro más reciente. 7. Ejecuta una conciliación de listas paginadas programada para detectar discrepancias. No utilices los Webhooks como tu único inventario ni hagas consultas antes de cada mensaje. ## Comportamiento de edición y eliminación * Edita solo 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 obtención. ## Publicar, revertir y retirar versiones Prefiere una versión paralela para cambios sustanciales: 1. Crea un nuevo nombre versionado para cada configuración regional requerida. Mantén sin cambios la versión aprobada actual. 2. Espera hasta que cada configuración regional de destino esté en `APPROVED` y luego valida sus variables, archivos multimedia, botones, categoría y contenido renderizado. 3. Enruta una proporción controlada de envíos aptos a la nueva versión y supervisa 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 con 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 anterior solo después de que las colas, campañas, configuraciones, pruebas y ventanas 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 alinearse con las políticas de Meta. * Revisa los detalles del rechazo antes de volver a crear el mismo contenido. * Utiliza un nuevo nombre cuando una plantilla eliminada o modificada sustancialmente no se pueda restaurar de forma segura. ## Lista de verificación para la puesta en marcha * [ ] Se han registrado el nombre, el propósito, el propietario, la categoría y la versión. * [ ] Cada variable tiene un único significado, formato, ejemplo seguro y regla de respaldo. * [ ] Los archivos multimedia y los botones superan las validaciones de formato, destino y ejemplos. * [ ] Cada configuración regional requerida se encuentra de forma independiente en `APPROVED`. * [ ] La ruta de envío rechaza cualquier estado distinto de `APPROVED`. * [ ] El procesamiento de Webhooks está verificado, es idempotente y se concilia con la obtención. * [ ] El despliegue puede restaurar una versión aprobada anterior. * [ ] Las colas, campañas, configuraciones, pruebas y guías operativas utilizan la versión prevista. Selecciona el idioma exacto y el código regional de la plantilla. Adapta plantillas de autenticación, marketing, utilidad, comercio, Flow y llamadas. Inspecciona el esquema de componentes completo. Gestiona los cambios de estado de revisión y de ciclo de vida. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.