Campañas

Una campaña es una plantilla aprobada enviada a 1..N destinatarios, cada uno con sus variables. Es el mismo endpoint tanto si recuerdas una sola factura vencida como si mandas los avisos de todo el mes. Todas las llamadas de esta guía necesitan el scope broadcasts.

1. Lista las plantillas del cliente

Las plantillas se aprueban por cuenta de WhatsApp, así que cada cliente tiene su propio catálogo. Lo leemos en vivo de Meta y devolvemos solo las APPROVED — ofrecer otra cosa daría un envío que Meta rechaza.

GET https://api.auphere.com/v1/partners/clients/{external_client_ref}/templates
Authorization: Bearer ak_live_…

{
  "templates": [
    {
      "name": "recordatorio_pago_vencido",
      "language": "es",
      "status": "APPROVED",
      "category": "UTILITY",
      "components": [
        { "type": "BODY",
          "text": "Hola {{cliente}}, tienes {{monto}} pendiente desde {{fecha}}." }
      ]
    }
  ]
}

Los nombres de las variables salen del componente BODY: esos {{nombres}} son exactamente las claves que debes enviar.

2. Envía

POST https://api.auphere.com/v1/partners/clients/{external_client_ref}/broadcasts
Authorization: Bearer ak_live_…
Content-Type: application/json

{
  "template_name": "recordatorio_pago_vencido",
  "language": "es",
  "idempotency_key": "invoice-991-reminder-1",
  "recipients": [
    { "phone": "+584241234567",
      "variables": { "cliente": "Ana", "monto": "36.00", "fecha": "12/08" } },
    { "phone": "+584249990000",
      "variables": { "cliente": "Luis", "monto": "120.50", "fecha": "10/08" } }
  ]
}

202 Accepted

{
  "broadcast_id": "8f1c…",
  "accepted": 1,
  "rejected": [
    { "phone": "+584249990000", "reason": "opted_out" }
  ]
}

202 significa encolado y durable, no entregado: a partir de ahí nuestro dispatcher se encarga del envío, los reintentos y el seguimiento. Los destinatarios que descartamos de entrada vuelven en rejected con su motivo, así que el número que recibes es el que realmente va a salir.

template_namestringRequerido

Debe estar APPROVED en la cuenta de WhatsApp de ese cliente al enviar.

languagestring

Código de idioma de la plantilla. Por defecto es.

recipients[].phonestringRequerido

E.164. Los duplicados dentro de una misma llamada se colapsan.

recipients[].variablesobject

Las claves deben coincidir con los parámetros nombrados de la plantilla. Los posicionales ({{1}}) se rechazan con 422.

idempotency_keystring

Muy recomendable. Repetir la misma clave devuelve 200 con el resultado original en vez de enviar dos veces. Usa un id de tu dominio (factura, recordatorio), no un valor aleatorio.

Lo que aplicamos por ti

• Bajas — quien respondió STOP a ese cliente se descarta y aparece en rejected.
• Verificación en vivo — la plantilla se comprueba contra Meta al enviar, así que una que se pausó entre el listado y el envío falla de forma visible, no en silencio.
• Solo parámetros nombrados — los posicionales se rechazan antes de encolar nada.
• Tope de destinatarios — 250 por llamada por defecto (el tier inicial de Meta para un número nuevo). Por encima devolvemos 413; trocea el envío o pídenos subirlo.
• Rate limit — por partner y por minuto. Al superarlo devolvemos 429.

3. Sigue la entrega

GET https://api.auphere.com/v1/partners/clients/{ref}/broadcasts/{broadcast_id}
Authorization: Bearer ak_live_…

{
  "broadcast_id": "8f1c…",
  "template_name": "recordatorio_pago_vencido",
  "status": "sent",
  "counts": { "delivered": 1 },
  "recipients": [
    { "phone": "+584241234567", "status": "delivered", "reason": null }
  ]
}