Plantillas

GET /v1/channels/{channel_id}/templates te devuelve las plantillas de WhatsApp de un canal con todo lo que el envío necesita: el nombre, el idioma, cómo se llaman sus variables, la categoría y en qué estado de aprobación está cada una.

Sirve para no tener que adivinar. Enviar una plantilla exige que content.name, content.language y las claves de content.variables coincidan exactamente con lo que Meta aprobó; si no coinciden, el envío se rechaza con 422 template_variables_mismatch. Con este listado, tu código puede construir la request a partir de lo que la plantilla declara, en vez de tener esos valores escritos a mano en algún lado.

La llamada

Necesitas una API key con el permiso channels:read (el mismo de GET /v1/channels).

curl https://api.alttos.ai/api/public/v1/channels/1b1a6d68-6e78-4717-aa04-5ace8614e907/templates \
  -H "Authorization: Bearer $ALTTOS_API_KEY"

{
  "data": [
    {
      "name": "recordatorio_cita",
      "language": "es",
      "status": "APPROVED",
      "category": "UTILITY",
      "parameter_format": "positional",
      "body": "Hola {{1}}, te recordamos tu cita del {{2}}.",
      "variables": [
        { "key": "1", "example": "Ana" },
        { "key": "2", "example": "12 de marzo a las 9:00" }
      ],
      "header": { "format": "TEXT", "text": "Tu cita", "variables": [] },
      "footer": "Responde CANCELAR para anularla",
      "buttons": [
        { "type": "URL", "text": "Ver mi cita", "url": "https://tu-sitio.com/citas", "phone_number": null }
      ],
      "rejected_reason": null
    }
  ]
}

La lista no se pagina: viene completa, en el orden en que la devuelve Meta. A diferencia de /v1/channels y /v1/contacts, que sí usan cursor, esta no lo va a necesitar: no sale de una tabla nuestra sino del catálogo de plantillas de tu cuenta de WhatsApp, que Meta ya acota. Puedes recorrer data entero sin preocuparte por páginas.

Los campos

Como en toda esta API, ignora los campos que no conozcas: dentro de /v1 solo agregamos campos, nunca cambiamos el significado de los que ya existen.

Los estados

El listado trae todas tus plantillas, no solo las que se pueden enviar. Esa es la mitad de su utilidad: saber que una plantilla está en revisión es lo que te evita programar un envío que va a fallar.

Intentar enviar cualquiera que no sea APPROVED responde 422 template_not_approved, con el estado que reportó Meta en detail.template_status.

De la plantilla al envío

El punto de todo esto es que variables te da las claves exactas. Una plantilla posicional:

{
  "name": "recordatorio_cita",
  "language": "es",
  "parameter_format": "positional",
  "variables": [{ "key": "1", "example": "Ana" }, { "key": "2", "example": "12 de marzo" }]
}

se envía así:

{
  "channel_id": "1b1a6d68-6e78-4717-aa04-5ace8614e907",
  "to": { "phone": "+573001234567" },
  "content": {
    "type": "template",
    "name": "recordatorio_cita",
    "language": "es",
    "variables": { "1": "Ana", "2": "12 de marzo a las 9:00" }
  }
}

Y una named, con variables igual a [{ "key": "nombre" }, { "key": "fecha" }], se envía con { "nombre": "Ana", "fecha": "12 de marzo a las 9:00" }. Los valores son siempre texto: ver las variables de la plantilla.

Cada cuánto consultarla

No hace falta llamarla antes de cada envío. Tus plantillas cambian cuando tú las tocas en Meta, no solas: lo razonable es consultarla cuando construyes o revisas la integración, y cachear el resultado de tu lado.

Del nuestro ya hay un cache de unos minutos que se invalida en cuanto Meta nos avisa que una plantilla cambió de estado, así que una plantilla recién aprobada aparece acá en segundos. Aun así, este endpoint consume tu cuota de lecturas por minuto como cualquier otro: ver Errores y límites.

Errores

El resto (401, 403, y el 429 por tu propia cuota de lecturas) es el de toda la API: ver Errores y límites.