The Engage API.

Create or update contacts

Upserts one contact or a batch of up to 100. Traits are shallow-merged into what is already stored, so you can sync a single field without sending the whole record. consent.marketing covers every channel; consent.channels.{whatsapp,email,sms} opts a person out of, or back in to, one channel. A consent change made here fires the same webhook as one made anywhere else.

{
  "data": { "id": "ct_9f2a...", "status": "created" }
}

Rate limit · 600 requests per minute per key

List contacts

Cursor-paginated. Pass the previous response’s nextCursor to continue; a null nextCursor means you have reached the end.

{
  "data": [
    {
      "id": "ct_9f2a...",
      "externalId": "user-1024",
      "phone": "+27820000000",
      "email": "someone@example.com",
      "consent": {
        "popiaAt": "2026-08-01T09:12:00.000Z", "marketingAt": "2026-08-01T09:12:00.000Z", "optedOutAt": null,
        "channels": { "whatsapp": { "optedOutAt": null }, "email": { "optedOutAt": "2026-09-02T14:03:00.000Z" }, "sms": { "optedOutAt": null } }
      }
    }
  ],
  "nextCursor": "ct_9f2a..."
}

Rate limit · 600 requests per minute per key

Delete a contact

Removes the contact your platform knows by this externalId, with its conversations and campaign history. Call it when a person is deleted or merged away on your side, so the record here does not live on holding their phone number.

{ "data": { "id": "ct_9f2a...", "status": "deleted" } }

Rate limit · 600 requests per minute per key

List campaigns with reports

Every campaign, newest first, each with its delivery report and settled cost. One row per channel: a send that went out on WhatsApp and email is two rows sharing a groupId. This is the feed a reporting page aggregates from, so it is paged and filterable by date.

{
  "data": [
    {
      "id": "cmp_7d1e...", "name": "Spring bursaries", "channel": "whatsapp", "groupId": "grp_2a...",
      "status": "completed", "startedAt": "2026-09-02T08:00:00.000Z", "completedAt": "2026-09-02T08:04:11.000Z",
      "report": { "sent": 12, "delivered": 980, "read": 610, "replied": 41, "failed": 9, "skipped_no_consent": 3, "reached": 1631, "opened": 651, "clicked": 0 },
      "costCents": 104300
    }
  ],
  "nextCursor": null
}

Rate limit · 600 requests per minute per key

Why people did not get it

Recipients who were skipped or failed, grouped by cause: bad numbers, no WhatsApp on the number, bounced email, spam complaints, and the two consent-gate skips. Each group carries up to 25 of the people affected with your externalId, so the record can be fixed on your side. disposition says whether sending again would help.

{
  "data": [
    { "code": "no_whatsapp", "label": "Number is not on WhatsApp", "kind": "failed", "disposition": "permanent", "count": 6,
      "people": [{ "contactId": "ct_9f2a...", "externalId": "user-1024", "label": "+27820000000 · A Person" }], "more": 0 }
  ]
}

Rate limit · 600 requests per minute per key

Create a campaign

Creates a draft, or sends immediately with start: true. Audience is one of three shapes: an existing segmentId, an inline filter, or an explicit recipient list of up to 25,000. Recipients that match no contact are returned in unmatchedIndexes rather than silently dropped.

{
  "data": { "id": "cm_4b71...", "status": "running", "matched": 1840, "unmatchedIndexes": [12, 907] }
}

Rate limit · 600 requests per minute per key

Campaign report

Live delivery counters and the metered cost so far. Safe to poll while a campaign runs.

{
  "data": {
    "id": "cm_4b71...",
    "status": "running",
    "counts": { "pending": 120, "sent": 1720, "delivered": 1688, "read": 1301, "replied": 344, "failed": 0 },
    "costCents": 172000
  }
}

Rate limit · 600 requests per minute per key

Cancel a scheduled campaign

Undoes a schedule before it starts: the campaign returns to draft and can be scheduled again. A campaign that has begun sending cannot be cancelled; the reply is 409.

{ "data": { "id": "cm_4b71...", "status": "draft" } }

Rate limit · 600 requests per minute per key

List conversations

Most recently active first, with unread counts, so you can render an inbox inside your own product.

Rate limit · 600 requests per minute per key

Send a free-form reply

Only works inside the 24-hour window opened by an inbound message. Outside it the call is rejected — send an approved template instead.

{
  "data": { "conversationId": "cv_2d19...", "messageId": "ms_77c0..." }
}

Rate limit · 600 requests per minute per key

Mark a conversation read

Clears the unread count, so your inbox and the Engage console agree.

Rate limit · 600 requests per minute per key

List templates and their approval status

Rate limit · 600 requests per minute per key

Submit a template for approval

Creates the template and submits it to Meta. Approval is asynchronous — watch the status field or subscribe to the webhook.

Rate limit · 600 requests per minute per key

Edit and resubmit a template

Meta treats an edit as a fresh review, so an approved template returns to pending.

Rate limit · 600 requests per minute per key

Delete a template

Rate limit · 600 requests per minute per key

Upload a header image

Base64 in, asset id out. Pass that id as headerImageAssetId when creating the template.

Rate limit · 600 requests per minute per key

Record events

One event or a batch of up to 100. Attach a contact by externalId, phone or email; an event with no contact is still stored.

{
  "data": { "id": "ev_18ca...", "status": "created" }
}

Rate limit · 600 requests per minute per key

Balance, rates and recent entries

Everything a wallet page needs. rates is your live rate card in cents; multiply by segments for SMS, where a message over 160 characters is billed as more than one. billingActive tells you whether sending is enabled — armed is the old name for the same field and is deprecated.

{
  "balanceCents": 250000,
  "reservedCents": 0,
  "availableCents": 250000,
  "billingActive": true,
  "lowBalance": false,
  "rates": { "waMarketingCents": 100, "waUtilityCents": 50, "waAuthCents": 50, "emailCents": 10, "smsCents": 30 },
  "entries": [{ "kind": "TOPUP_CARD", "amountCents": 250000, "createdAt": "2026-08-01T08:00:00.000Z" }]
}

Rate limit · 600 requests per minute per key

Set the billing email

Where receipts and low-balance notices go.

Rate limit · 60 requests per minute per key

The full ledger

Every movement on the balance, newest first, paged, with a date range. format=csv returns the same rows as a file for the accountant. GET /wallet stops at the last 30; this does not.

{
  "data": [{ "id": "we_...", "type": "debit_usage", "amountCents": -104300, "balanceAfterCents": 145700, "reference": "campaign:cmp_7d1e...", "note": "Spring bursaries", "at": "2026-09-02T08:04:11.000Z" }],
  "nextCursor": null
}

Rate limit · 600 requests per minute per key

Top-up history

Every top-up started, with its Paystack reference and, once paid, enough of the receipt to recognise the payment: card type and last four digits. Nothing here can charge the card.

{
  "data": [{ "id": "wt_...", "reference": "engtu_...", "amountCents": 250000, "status": "paid", "payerEmail": "finance@example.com", "paidAt": "2026-09-01T08:00:00.000Z", "receipt": { "channel": "card", "cardType": "visa", "last4": "4081", "bank": "TEST BANK" } }],
  "nextCursor": null
}

Rate limit · 600 requests per minute per key

Start a top-up

Returns a Paystack authorisation URL to send the payer to. The balance moves only once the payment is verified.

{
  "reference": "tp_5a90...",
  "authorizationUrl": "https://checkout.paystack.com/..."
}

Rate limit · 20 requests per minute per key

Verify a top-up

Confirms a payment and credits the wallet. Idempotent — verifying twice credits once.

Rate limit · 120 requests per minute per key

Configure automatic top-up

Charges a saved card when the balance falls below your threshold, so a campaign never stops mid-send.

Rate limit · 60 requests per minute per key

Monthly statement

One period, or a range of up to 24 (from/to). Lines are per channel at your rates; paidFromWalletCents is the usage the balance already covered; dueCents is what remains. The current period includes a linear projection.

{
  "data": {
    "period": "2026-08", "currency": "ZAR",
    "lines": [{ "key": "wa_marketing", "description": "WhatsApp — marketing messages", "quantity": 1043, "unitCents": 100, "amountCents": 104300 }],
    "baseFeeCents": 2150000, "subtotalCents": 104300, "totalCents": 2254300,
    "paidFromWalletCents": 104300, "dueCents": 2150000,
    "isCurrentPeriod": false, "projectedTotalCents": null,
    "invoice": { "id": "inv_...", "number": "ENG-EXAMPLE-0007", "status": "PAID", "issuedAt": "2026-09-01T06:00:00.000Z", "dueAt": "2026-09-08T06:00:00.000Z", "paidAt": "2026-09-05T10:12:00.000Z" }
  }
}

Rate limit · 600 requests per minute per key

List invoices

Every invoice raised, newest period first. Line items and totals are frozen at issue. overdue is true for an issued invoice past its due date.

Rate limit · 600 requests per minute per key

One invoice

The same record with the billed-to name, for rendering a printable copy.

Rate limit · 600 requests per minute per key

Messages and spend by channel by month

The metered counts behind each statement, priced at your rates, for a range of up to 24 months. Defaults to the last twelve.

{
  "data": [{ "period": "2026-08", "lines": [{ "key": "sms", "channel": "sms", "category": "standard", "quantity": 4120, "unitCents": 30, "amountCents": 123600 }], "baseFeeCents": 2150000, "subtotalCents": 123600, "totalCents": 2273600, "projectedTotalCents": null }]
}

Rate limit · 600 requests per minute per key

Opt-ins, opt-outs and reach

timeline: consent changes by month, kind, scope (all_channels or one channel) and route — a STOP on WhatsApp, an email unsubscribe, a spam complaint, a sync. snapshot: how many contacts can be reached on each channel today, how many have opted out of what, and new contacts per month.

{
  "data": {
    "from": "2025-09", "to": "2026-09",
    "timeline": [{ "month": "2026-09", "kind": "opt_out", "scope": "whatsapp", "source": "whatsapp_keyword", "count": 14 }],
    "snapshot": { "contacts": 35210, "consented": 33980, "reachable": { "whatsapp": 33100, "email": 21400, "sms": 33100 }, "optedOut": { "all": 1230, "whatsapp": 140, "email": 380, "sms": 22 }, "newContactsByMonth": [{ "month": "2026-09", "count": 2100 }] }
  }
}

Rate limit · 600 requests per minute per key

Channel status

Whether WhatsApp, SMS and email are configured and active on your workspace.

Rate limit · 600 requests per minute per key