Campaigns

A campaign is one approved template sent to 1..N recipients, each with their own variables. It is the same endpoint whether you are nudging one overdue invoice or sending the whole month’s reminders. Every call in this guide needs the broadcasts scope.

1. List the client’s templates

Templates are approved per WhatsApp account, so each client has their own catalogue. We read it live from Meta and return only the APPROVED ones — offering anything else would produce a send Meta rejects.

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}}." }
      ]
    }
  ]
}

Read the variable names from the BODY component: those {{names}} are exactly the keys you must send.

2. Send

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 means queued and durable, not delivered: from here our dispatcher handles sending, retries and status tracking. Recipients we refuse up front come back in rejected with a reason, so the count you get is the count that will actually go out.

template_namestringRequired

Must be APPROVED in that client’s WhatsApp account at send time.

languagestring

Template language code. Defaults to es.

recipients[].phonestringRequired

E.164. Duplicates within one call are collapsed.

recipients[].variablesobject

Keys must match the template’s named parameters. Positional ones ({{1}}) are rejected with 422.

idempotency_keystring

Strongly recommended. Replaying the same key returns 200 with the original result instead of sending twice. Use an id from your domain (invoice, reminder), not a random value.

What we enforce for you

• Opt-outs — anyone who replied STOP to that client is dropped and reported in rejected.
• Live template check — verified against Meta at send time, so a template paused between listing and sending fails loudly instead of silently.
• Named parameters only — positional placeholders are rejected before anything is queued.
• Recipient cap — 250 per call by default (Meta’s starting tier for a new number). Above it you get 413; split the send or ask us to raise it.
• Rate limit — per-partner, per-minute. Over it you get 429.

3. Track delivery

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 }
  ]
}