WhatsApp API Documentation

The Macra WhatsApp API lets your business connect a WhatsApp Business number to your own systems, send messages programmatically, and receive inbound messages on a webhook. It sits in front of a managed WhatsApp connection so you never handle QR codes or session state directly. You only talk to a small JSON/HTTPS API.

Getting Started

1. Apply for access. Submit the signup form with your business details, the WhatsApp Business number you want to connect, and a business permit or company registration certificate. Every application is reviewed manually to keep the platform limited to verified businesses.
2. Wait for review. Applications are typically reviewed within a few business days. You'll be contacted on the phone number you provided if anything is missing.
3. Get your API key. Once approved, Macra Systems issues your account with an initial API key. From then on you can create and revoke your own keys anytime from the dashboard. Each key is shown once at creation, so store it somewhere safe, since it can't be retrieved again afterwards (only revoked and replaced with a new one).
4. Pay the onboarding fee. See Onboarding Fee — required before you can connect WhatsApp or create additional API keys.
5. Connect your WhatsApp number. Call POST /v1/whatsapp/connect and enter the returned pairing code on the WhatsApp Business phone.
6. Start integrating. Send messages with POST /v1/messages/send and receive inbound messages on your webhook URL.

Onboarding Fee

Every account owes the same one-time onboarding fee — a standard amount set platform-wide by Macra Systems, not negotiated per account. It's separate from the daily message limit and is charged once, not on a recurring schedule.

Pay it from the dashboard, under "Onboarding Fee" — card and mobile money (M-Pesa) are both supported. Payment is processed by Paystack and verified server-side before your account is marked paid. There's no API endpoint for this: it's dashboard-only.

Authentication

Every request to a /v1/ endpoint must include your API key in an X-Api-Key header. There is no OAuth flow, session, or bearer-token exchange: the key itself is the credential.

X-Api-Key: mwa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed mwa_ and are account-scoped: one key authenticates as one account and everything that account is entitled to (its connected WhatsApp number, its message history, its rate limit).

An account can hold multiple active keys at once (for example, one per environment). Create and revoke keys anytime from the dashboard under API Keys; revoking one takes effect immediately.

Base URL

https://macrasystems.com/wa/v1

All endpoint paths below are relative to this base URL. The API only accepts and returns application/json, and every response, success or error, is a JSON object.

Connect WhatsApp

curl -X POST https://macrasystems.com/wa/v1/whatsapp/connect \
  -H "X-Api-Key: mwa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "pairing_code": "ABCD-1234",
  "status": "qr_ready"
}

{
  "pairing_code": null,
  "status": "ready"
}

Connection Status

curl https://macrasystems.com/wa/v1/whatsapp/status \
  -H "X-Api-Key: mwa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "status": "connected"
}

Send a Message

curl -X POST https://macrasystems.com/wa/v1/messages/send \
  -H "X-Api-Key: mwa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "254712345678", "message": "Hello from Macra WhatsApp API"}'

{
  "id": "true_254712345678@c.us_3EB0...",
  "ack": "sent"
}

Send a Document

curl -X POST https://macrasystems.com/wa/v1/messages/send-document \
  -H "X-Api-Key: mwa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "254712345678", "document_base64": "JVBERi0xLjQK...", "document_mimetype": "application/pdf", "filename": "Invoice-1024.pdf", "caption": "Invoice #1024"}'

{
  "messageId": "true_254712345678@c.us_3EB0...",
  "timestamp": 1719312000
}

Receiving Messages (Webhooks)

To receive WhatsApp messages sent to your connected number, set a webhook URL on your account. Every inbound message is relayed there as an HTTP POST as soon as it arrives.

Payload

{
  "event": "message_received",
  "from": "254712345678",
  "message": "Hi, is this order ready?",
  "timestamp": 1732012345
}

Verifying the signature

Every delivery includes an X-Macra-Signature header so you can confirm it came from Macra Systems and wasn't sent by someone who simply guessed or found your webhook URL:

X-Macra-Signature: sha256=<hex-encoded HMAC-SHA256>

The signature is an HMAC-SHA256 of the raw request body, keyed with your account's webhook signing secret (visible under "Inbound Webhook" in the dashboard, and rotatable there at any time). Recompute it over the exact bytes you received and compare with a constant-time check - don't re-serialize the parsed JSON first, since that isn't guaranteed to produce identical bytes.

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_MACRA_SIGNATURE'] ?? '';
$signature = str_starts_with($header, 'sha256=') ? substr($header, 7) : '';
$expected = hash_hmac('sha256', $raw, $yourWebhookSecret);

if ($signature === '' || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Notes

• Requests are sent as Content-Type: application/json with a 10-second delivery timeout and are not retried on failure, so your endpoint should respond quickly with a 2xx status.
• Reject any delivery with a missing or invalid X-Macra-Signature before acting on it.
• Only the message text is relayed today; media, location, and other message types aren't forwarded yet.

Rate Limits

Each account has a daily limit on messages sent via /v1/messages/send, counted from midnight and reset daily. The default on the free plan is 100 messages/day. Receiving messages is never rate-limited.

Once the limit is reached, /v1/messages/send returns 429 Daily message limit reached until it resets. There is no rate limit on /v1/whatsapp/connect or /v1/whatsapp/status beyond normal fair use.

Errors

Errors are returned as a JSON object with a single detail field describing what went wrong, alongside the HTTP status code.

{
  "detail": "Invalid API key"
}

Support

For questions about your application, API keys, webhook setup, or rate limits, reach out via the contact page and include your account email so we can look you up quickly.