Developer API

Plug WhatzAI into your own tools

Your website, your online shop or your software can read your contacts and conversations, add contacts and send a WhatsApp message. The API is part of the Agency plan.

Not a technical person?

An API is a doorway reserved for software. It lets another tool talk to WhatzAI on your behalf, without anyone opening the dashboard. Examples:

Your online shop tells the customer on WhatsApp when their order is ready.
A form on your website adds every new prospect to your WhatzAI contacts.
Your management software shows a customer's WhatsApp history.

You do not have to program anything yourself: create a key (step 1) and pass this page to the person who looks after your website or software.

1. Create a key

In your dashboard: Settings → API key (the app is in French for now) → “Créer une clé”. It starts with wz_live_ and is shown only once. Keep it secret, server-side only.

Two key types: read-only (view contacts and conversations) or read and write (also add a contact and send a message). Give each tool the minimum it needs. You can create up to 5 keys, one per tool.

2. Call the API

Base address: https://whatzai-backend.onrender.com. Send your key in the Authorization header. Responses are JSON.

curl https://whatzai-backend.onrender.com/v1/contacts?limit=10 \
  -H "Authorization: Bearer wz_live_YOUR_KEY"

Send a message:

curl -X POST https://whatzai-backend.onrender.com/v1/messages \
  -H "Authorization: Bearer wz_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "AGENT_ID", "to": "+237696213325", "text": "Your order is ready." }'

3. The routes

GET/v1/account

Your account: ID, email, company, plan.

GET/v1/agents

Your agents and numbers, with their ID (needed to send a message).

GET/v1/contacts

Your contacts, newest first.

Parameters: limit (1 to 100, default 50), after (ID of the last contact received, for the next page), phone (search a number).

POST/v1/contacts

Add a contact.

Body: phone (required, with country code), name, email. Returns 409 if the number already exists.

{ "phone": "+237696213325", "name": "Marie" }

GET/v1/conversations

Your conversations, most recent first.

Parameter: limit (1 to 100).

GET/v1/conversations/{id}/messages

The latest messages of a conversation.

Field “from”: contact (the customer), ai (the agent), human (your team or your API).

POST/v1/messages

Send a WhatsApp text message from an agent's number.

Body: agentId, to (number with country code), text (4,096 characters maximum).

{ "agentId": "…", "to": "+237696213325", "text": "Your order is ready." }

4. Get notified of every incoming message

Instead of polling the API in a loop, give WhatzAI an address (Settings → API key → “Être prévenu à chaque message reçu”). As soon as a customer writes to you, WhatzAI sends a JSON POST request to that address:

{
  "event": "message.received",
  "createdAt": "2026-10-12T08:30:00.000Z",
  "data": {
    "messageId": "…",
    "conversationId": "…",
    "agentId": "…",
    "contact": { "id": "…", "phone": "237696213325", "name": "Marie" },
    "type": "text",
    "text": "Hello, is my order ready?"
  }
}

The address must be public and start with https://.
Reply quickly with a 200 code. WhatzAI waits 5 seconds at most and does not retry a failed call: to miss nothing, complement it with GET /v1/conversations.
The “Send a test” button sends a ping event to check your address.
Verify the signature. Every call carries the X-WhatzAI-Signature header, equal to sha256= followed by the HMAC-SHA256 of the raw request body, computed with your secret. Reject any call whose signature does not match.

// Node.js example
import { createHmac, timingSafeEqual } from "node:crypto";

function isFromWhatzAI(rawBody, receivedSignature, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(receivedSignature || "");
  return a.length === b.length && timingSafeEqual(a, b);
}

5. Rules to know

24-hour window. WhatsApp only allows a free-form message within 24 hours of the customer's last message on that number. Outside it, the API answers 422 and nothing is sent.
Opt-out. A contact who replied STOP is never contacted (403).
Limits. 240 requests per minute per account, of which 60 modifications. Beyond that: 429.
Your data only. A key only gives access to the account that created it.
Lost or exposed key. Delete it in Settings: it stops working immediately.

6. Error codes

400	A field is missing or invalid. The message says which one.
401	Missing or invalid key.
403	Agency plan inactive, read-only key used to modify data, or contact opted out (they replied STOP).
404	The item does not exist in your account.
409	The contact already exists.
422	24-hour window closed: the customer has not written for more than 24 hours.
429	Too many requests. Wait a minute.
502	WhatsApp refused the message. Try again later.

An error always returns a message field that explains the cause. For now this message is written in French.

A question, or a need that is not covered? difisoltech@gmail.com