Cómo crear y administrar plantillas de WhatsApp mediante la API

📋 Antes de comenzar

Asegúrate de contar con los siguientes elementos para realizar tus integraciones exitosamente:

Token UUID válido: Es tu credencial principal. Identifica a tu empresa automáticamente (por lo que no requiere enviar el companyId en el JSON).
Número de canal: Debes tener a la mano el número de teléfono operativo, incluyendo siempre el código de país (ej. +5491112345678).
Cliente HTTP: Utiliza herramientas para pruebas de API como Postman, Insomnia o directamente la terminal con curl.

⚙️ Pasos de Configuración

Paso 1: Encabezado de autorización

Cada solicitud que realices a la API requiere estrictamente los siguientes encabezados (headers). Sin ellos, el servidor rechazará la petición con un error 401 Unauthorized.

HTTP

Authorization: Bearer <tu-token-uuid>
Content-Type: application/json

💡 Consejo: Como el token ya identifica automáticamente a tu empresa en nuestra base de datos, nunca incluyas el campo companyId en el cuerpo de la solicitud; la API lo resuelve internamente de forma segura.

Paso 2: Crear una plantilla (POST)

Utiliza el método POST para registrar y enviar a revisión una nueva plantilla en Meta a través del flujo de Atom.

Campos obligatorios:

Campo	Tipo	Descripción
`channelNumber`	string	Número de teléfono del canal (ej. +5491112345678).
`platform`	string	Siempre debe ser el valor `"whatsapp"`.
`language`	string	Código oficial de idioma (ej. `"es"`, `"en_US"`, `"pt_BR"`).
`category`	string	Tipo de contenido: `"MARKETING"`, `"UTILITY"` o `"AUTHENTICATION"`.
`components`	array	El arreglo con los bloques que forman el mensaje (texto, botones, etc.).
`groupIds`	string[]	IDs de los grupos autorizados para usarla. (Usa `["ALL"]` para todos).
`groupNames`	string[]	Nombres de los grupos que coinciden con los IDs (ej. `["ALL"]`).

Campos opcionales:

Campo	Tipo	Por defecto	Descripción
`name`	string	—	Nombre único de la plantilla. Utiliza siempre formato `snake_case`.
`makeUnique`	boolean	`false`	Si envías `true`, añade un sufijo aleatorio para evitar colisiones de nombre.

Ejemplo A — Plantilla simple (Encabezado de texto + Cuerpo)

BASH

curl -X POST https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api \
  -H "Authorization: Bearer <tu-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "channelNumber": "+5491112345678",
      "platform": "whatsapp",
      "language": "es",
      "category": "UTILITY",
      "name": "bienvenida_simple",
      "groupIds": ["ALL"],
      "groupNames": ["ALL"],
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Bienvenido" },
        { "type": "BODY", "text": "Gracias por contactarnos. Pronto te atenderemos." }
      ]
    }'

Ejemplo B — Plantilla con variables y botones de respuesta rápida (Nota: Usa los marcadores {{1}}, {{2}} para valores dinámicos. Es obligatorio incluir el objeto example con valores de muestra, ya que Meta lo exige para la revisión).

BASH

curl -X POST https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api \
  -H "Authorization: Bearer <tu-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "channelNumber": "+5491112345678",
      "platform": "whatsapp",
      "language": "es",
      "category": "UTILITY",
      "name": "pedido_con_params",
      "groupIds": ["ALL"],
      "groupNames": ["ALL"],
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Solicitud de pedido" },
        {
          "type": "BODY",
          "text": "Estimado/a {{1}}, gracias por su interés en el modelo {{2}}.",
          "example": { "body_text": [["Nombre_Cliente", "Modelo_Vehiculo"]] }
        },
        { "type": "FOOTER", "text": "Estamos aquí para servirle." },
        {
          "type": "BUTTONS",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "Confirmar pedido" },
            { "type": "QUICK_REPLY", "text": "Modificar pedido" }
          ]
        }
      ]
    }'

Paso 3: Actualizar una plantilla existente (PATCH)

Utiliza este método para actualizar los metadatos internos de una plantilla en Atom.

⚠️ Importante: El contenido real de WhatsApp (componentes, texto, botones e idioma) NO puede modificarse mediante API una vez que la plantilla fue creada/aprobada.

Campos disponibles (Al menos uno es requerido en el body):

Campo	Tipo	Descripción
`description`	string	Nombre interno de visualización para la plantilla dentro de Atom.
`groupIds`	string[]	IDs de grupos autorizados para usar esta plantilla.
`groupNames`	string	Nombres de grupos correspondientes a los `groupIds`.
`active`	boolean	`true` para habilitar su uso, `false` para deshabilitarla.

Ejemplo de solicitud PATCH:

BASH

curl -X PATCH "https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api?channelNumber=+5491112345678&page=1" \
  -H "Authorization: Bearer <tu-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "Promo verano 2025",
      "active": false
    }'

Paso 4: Listar plantillas (GET)

Recupera todas las plantillas asociadas a tu canal. Este endpoint soporta paginación y ordenamiento para facilitar el manejo de grandes volúmenes de datos.

Parámetros de consulta (Query Params):

Parámetro	Tipo	Requerido	Por defecto	Descripción
`channelNumber`	string	Sí	—	Número de teléfono exacto para filtrar.
`page`	número	No	`1`	Número de página a consultar.
`size`	número	No	`10`	Cantidad de resultados por página.
`sort`	string	No	`"asc"`	Dirección del ordenamiento: `"asc"` o `"desc"`.

Ejemplo de solicitud GET:

BASH

curl -X GET "https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api?channelNumber=+5491112345678&page=1&size=20&sort=desc" \
  -H "Authorization: Bearer <tu-token-uuid>"

💡 Recomendaciones y Buenas Prácticas

Nomenclatura limpia: Utiliza siempre el formato snake_case (ej. bienvenida_cliente_nuevo) en el nombre de tus plantillas para evitar errores de sintaxis en la validación de Meta.
Uso de makeUnique: Si experimentas errores de "nombre duplicado" al intentar reemplazar una plantilla que acabas de borrar, envía "makeUnique": true. La API añadirá automáticamente un sufijo numérico para evitar colisiones.
Formatos de Header: Recuerda que además de "format": "TEXT", los encabezados de WhatsApp soportan contenido multimedia utilizando "format": "IMAGE", "VIDEO", o "DOCUMENT".

⚠️ Solución de Problemas Comunes

Si tus llamadas a la API fallan, revisa estos puntos críticos:

Error 401 (Unauthorized): El token UUID es incorrecto, está vencido, o el encabezado no tiene exactamente el formato Bearer <tu-token>.
Error 404 (Channel not found): El channelNumber enviado no está registrado o no se encuentra activo dentro de tu cuenta de Atom. Asegúrate de incluir el código de país sin el símbolo + si la API te arroja errores de formato de URL, o tal cual está registrado en plataforma.
Plantilla atascada en estado PENDING: Recuerda que la revisión es un proceso de auditoría externo realizado por Meta (WhatsApp). Puede tardar desde un par de segundos hasta 24 horas en ser aprobada.

¡Automatiza tu comunicación a gran escala! 🚀

Integrar la gestión de plantillas mediante nuestra API te permite escalar tu operación, sincronizar tus sistemas internos con Atom y mantener tus campañas de WhatsApp funcionando de manera ininterrumpida y sin intervención manual. ✅