WhatsApp Business API — Developer Guide

Welcome to the Notify Africa WABA API! This guide covers everything you need to send WhatsApp text and template messages using RESTful endpoints.

Quick Start

First, create or obtain your API key from API Management. WABA endpoints use that same API key as a Bearer token — the identical key you already use for SMS also works here once WhatsApp is enabled on it.

All WABA endpoints expect:

Authorization: Bearer {API-KEY}
Content-Type: application/json

:::info Base URL All endpoints below are relative to:

https://api.notify.africa

:::

:::info One API key, multiple services A Notify Africa API key can be authorized for more than one service (SMS, WhatsApp) at the same time. If your existing key already works for SMS, ask us to add WhatsApp authorization to it — you do not need a separate key for WABA. :::

Endpoints Overview

Tip: All endpoint paths are relative to the base URL above. /v1/waba-api is the one, stable WABA API path — new capabilities are always added under it, not a separate version.

1. Send a WhatsApp Text Message

Sends a plain-text WhatsApp Business message to one or more recipients.

:::info WhatsApp's messaging window Freeform text is only deliverable within Meta's 24-hour customer-service window for a given recipient (i.e., the recipient messaged your WhatsApp number recently). If the window is closed, this endpoint returns a normalized error telling you an approved template is required — see Error Handling. :::

Example Request (cURL)

curl -X POST https://api.notify.africa/v1/waba-api/messages/text \
  -H "Authorization: Bearer {API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["255700000001"],
    "text": "Hello from the Notify Africa WABA API"
  }'

Response Sample

{
  "status": 200,
  "message": "WhatsApp text message send attempted",
  "timestamp": "2026-09-03T10:15:00.000Z",
  "path": "/v1/waba-api/messages/text",
  "data": {
    "results": [
      {
        "to": "255700000001",
        "success": true,
        "messageId": "d9b54c80-8a63-4f8b-83c8-71f2439f5429",
        "wamid": "wamid.HBgLMjU1NzAwMDAwMDAxFQIAERgSODZBRD...",
        "status": "accepted",
        "error": null
      }
    ]
  },
  "pagination": null
}

Helpful Notes

• to accepts either a single string or an array of phone numbers.
• Duplicate recipients (exact string match) are removed automatically before sending.
• The API processes up to 500 recipients per request. Sending more than 500 returns a 400 validation error — the request is rejected, not silently truncated.
• Each result entry returns its own success, messageId, wamid, status, and error.
• An idempotency_key field is optional. If you provide one, repeated requests with the same key and payload return the original messageId instead of sending again. If you omit it, each request sends normally — you are never required to supply one.

2. Send a WhatsApp Template Message

Sends an approved WhatsApp template message to one or more recipients.

Example Request (cURL) — With Parameters

curl -X POST https://api.notify.africa/v1/waba-api/messages/template \
  -H "Authorization: Bearer {API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["255700000001"],
    "template_name": "hello_world",
    "template_parameters": {
      "body": {
        "1": "John",
        "2": "Acme Ltd",
        "3": "INV-2026-001"
      }
    }
  }'

Example Request (cURL) — Without Parameters

curl -X POST https://api.notify.africa/v1/waba-api/messages/template \
  -H "Authorization: Bearer {API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["255700000001"],
    "template_name": "hello_world",
    "template_parameters": {}
  }'

Response Sample

{
  "status": 200,
  "message": "WhatsApp template message send attempted",
  "timestamp": "2026-09-03T10:16:00.000Z",
  "path": "/v1/waba-api/messages/template",
  "data": {
    "results": [
      {
        "to": "255700000001",
        "success": true,
        "messageId": "a1b2c3d4-1234-4f8b-83c8-71f2439f5429",
        "wamid": "wamid.HBgLMjU1NzAwMDAwMDAxFQIAERgSNjQ1R...",
        "status": "accepted",
        "error": null
      }
    ]
  },
  "pagination": null
}

Helpful Notes

• template_name must match an approved template already available in your connected WhatsApp Business account.
• template_parameters can be sent as a flat object ({"1": "value"}) or grouped under body, header, and buttons.
• Body parameters are ordered by key, so numeric keys such as "1", "2", and "3" are the safest choice.
• Media URLs supplied as template parameter values are converted into WhatsApp image, video, or document components automatically based on the file extension, when the template's header/body expects media.
• The same recipient-array, dedup, 500-max, and idempotency rules from the text-send endpoint apply here.

Error Handling

All errors — validation, authentication, and provider (WhatsApp) failures — use the same envelope as a success response, with data describing the problem instead of a result:

{
  "status": 400,
  "message": "Recipient count exceeds the maximum of 500 per request",
  "timestamp": "2026-09-03T10:17:00.000Z",
  "path": "/v1/waba-api/messages/text",
  "data": {
    "code": "RECIPIENT_LIMIT_EXCEEDED"
  },
  "pagination": null
}

Common status codes:

• 400 — validation error (bad payload, recipient count exceeded, etc.).
• 401 — missing or invalid API key.
• 403 — API key doesn't have WhatsApp authorized, or key is revoked/expired.
• 404 — template or message not found.
• 422 — the requested action isn't currently permitted (e.g. freeform text outside the messaging window — you'll get a message telling you to use an approved template instead).
• 429 — you've hit a rate limit; back off and retry.
• 5xx — something went wrong on our side or with the upstream provider; safe to retry with backoff.

Notify Africa never forwards a raw WhatsApp/Meta provider error directly — failures are always normalized into the shape above so your error handling doesn't need to understand Meta's API.

Pro Tips

• Store your API key in environment variables and never hard-code it in source code.
• Use the text endpoint only within an open customer-service window; use the template endpoint for anything outside that window or for first-contact/outbound notifications.
• Log the returned messageId for support and reconciliation.

Need Help?

If you need anything, reach us via WhatsApp, phone, or email:

Quick links

• WhatsApp: Chat on WhatsApp
• Phone call: Call +255 759 818 157
• Email: support@notify.africa

Happy Sending! 🚀