API Reference

Credits & billing

Messaging is pay-as-you-go at $0.01 per message ($10 = 1,000 credits). Buy credits from Dashboard → Billing.

1. Choose a preset ($10 = 1,000 credits) or enter a custom amount (min $1 = 100 credits, max $500). Credits always equal the amount in cents.
2. Submit to create a pending payment and receive a unique reference like ZN-XXXXXXXX.
3. Pay by bank transfer or mobile money using the instructions shown, quoting your reference.
4. An admin approves the payment; credits are added exactly once and appear in your balance and ledger.

Pending requests can be cancelled before approval. Payments are manual at launch; gateway support is pluggable and will be documented here when enabled.

Integration service

Need it wired into your product? Add the done-for-you integration service for a one-time $20.00. Submit your requirements and contact channel from the Billing page. You get a pending $20 payment with its own reference; once approved, the order moves to paid and our team starts work. Order progress is visible on the billing page (requested → paid → in_progress → delivered).

Authentication

Create an API key in the dashboard, then send it on every request using either header:

Authorization: Bearer zn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
X-API-Key: zn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are shown once at creation and stored only as a SHA-256 hash. Revoke a key any time from Dashboard → API Keys.

Returns your account status, credit balance and WhatsApp connection state.

curl https://znotice.consultbofa.com/api/v1/status \
  -H "Authorization: Bearer $ZNOTICE_API_KEY"

{
  "ok": true,
  "api_version": "v1",
  "user": { "id": 1, "name": "Jane", "email": "jane@example.com" },
  "credits": 1000,
  "whatsapp": { "session": "zn_1", "status": "disconnected", "phone_number": null },
  "api_keys_active": 1,
  "key": { "label": "Default", "prefix": "zn_live_abcd" }
}

Send a WhatsApp message. Costs 1 credit per message. Requires a connected WhatsApp session.

curl -X POST https://znotice.consultbofa.com/api/v1/send \
  -H "Authorization: Bearer $ZNOTICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"250788123456","message":"Hello from ZNotice"}'

Body: phone (country-coded digits, or a national number starting with 0 to use the default country code), message (1–4096 chars), optional media_url (the message becomes the caption).

media_url: public http(s) URL on port 80/443. ZNotice fetches the file server-side behind an egress guard: private, loopback, link-local and reserved addresses are blocked, DNS is pinned, redirects are capped at 3 (each re-validated), timeout 30s, max 16MB, and only image/*, video/*, audio/* or application/pdf are accepted. SVG (image/svg+xml, image/svg) and any +xml content type are explicitly rejected.

{ "ok": true, "id": 42, "message_id": "true_250788123456@c.us_3EB0...", "credits_remaining": 999 }

If the engine rejects the send, the credit is automatically refunded and a failed message row is stored.

List your recent messages. Optional ?limit=50 (1–200).

curl "https://znotice.consultbofa.com/api/v1/messages?limit=20" \
  -H "X-API-Key: $ZNOTICE_API_KEY"

{
  "ok": true,
  "count": 2,
  "data": [
    { "id": 42, "to_number": "250788123456", "body": "Hello from ZNotice",
      "media_url": null, "status": "sent", "wpp_message_id": "…", "credits_charged": 1,
      "created_at": "2026-09-10T12:00:00.000Z" }
  ]
}

Rate limits

Errors

Errors return a JSON object with ok:false and an error code.