On this page
Getting started
Introduction
The MationX WhatsApp API puts WhatsApp numbers that live on real Android phones behind a REST endpoint. Your system calls the API, a phone types and sends the message in the WhatsApp app, and the result comes back to your callback URL. Incoming messages, calls and account changes come back as webhook events.
- Messages go out from the real WhatsApp or WhatsApp Business app on a physical phone, not from WhatsApp Web.
- New numbers are checked with WhatsApp before anything is sent.
- A message is never left behind as a draft.
- The disappearing messages info screen is dismissed on its own.
- Sends and warm-up share one screen lock, so they never collide.
- A restricted phone answers ACCOUNT_RESTRICTED at once, not after a timeout.
# base URL
https://hook.mationx.cloud
# every route sits under your secret
/p/{webhookSecret}/<route>?deviceId={deviceId}
# headers
Authorization: Bearer {apiToken}
Content-Type: application/json- 1
Get your credentials
When your phones are set up you receive an API token, a webhook secret and the id or handle of each phone.
- 2
Send your first message
POST to the send endpoint with the recipient and the text. The API answers 202 at once.
- 3
Receive the result
The phone posts the result to your callbackUrl: sent, or failed with an error code. Missed one? Ask the status endpoint.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/send?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15551234567",
"message": "Hi Sarah, your order #1042 is ready for pickup today after 2 pm.",
"app": "business",
"requestId": "order-1042",
"callbackUrl": "https://example.com/mationx/callback"
}'Every request carries your API token as a bearer token in the Authorization header. The webhook secret is part of the URL and identifies your account. Keep both on your server, never in a browser or an app. A missing or wrong token answers 401; we rotate either one whenever you ask.
Each request names one phone with deviceId, its MationX id or the handle you gave it. Every phone has its own queue of up to 5 waiting requests: if it is busy with warm-up or another send, your request waits its turn. A request that finds the queue full shows as queueFull in the summary and does not run. If the phone is offline at that moment, the request is not kept for later: it shows as offline in the summary and no callback is sent, so retry it on another phone. Sends and warm-up share one screen lock, so they never collide.
Authorization: Bearer {apiToken}
Content-Type: application/json
# the secret is in the path
POST /p/{webhookSecret}/send?deviceId=phone-01The API accepts up to 50 requests a second from one IP; above that it answers 429 with a plain text body and the standard RateLimit-* headers. The real limit is WhatsApp: a phone types and sends like a person, and how many new chats a number should start a day depends on its age and on how many people reply. See Sending volume.
Every endpoint and event on this page carries one of three labels.
- LiveOn every account today.
- AvailableThe phones do this today. We switch the endpoint on for your account when you ask.
- On requestBuilt for your setup, usually within days.
HTTP/1.1 429 Too Many Requests
RateLimit-Policy: 50;w=1
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1
Too many webhook requests from this IP, please try again later./p/{webhookSecret}/sendSends a text message from the real WhatsApp or WhatsApp Business app on the phone you name. The call returns 202 at once and the result arrives at your callbackUrl.
If the phone is busy with warm-up or another send, the request waits in that phone's queue, up to 5 waiting requests per phone. If the target phone is offline at that moment, the request is not kept for later: it shows as offline in the summary and no callback is sent. Retry it on another phone.
A new number is checked with WhatsApp before anything is sent, a message is never left behind as a draft, and the disappearing messages info screen is dismissed on its own. A restricted phone answers ACCOUNT_RESTRICTED straight away, not after a timeout.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
Body
phonestringrequiredThe recipient, in E.164 or digits. "+" and spaces are stripped.
messagestringThe message text.
app"personal" | "business"Which WhatsApp app on the phone sends it. Default: business.
validateOnlybooleanOnly check whether the number is on WhatsApp. Nothing is sent. See Validate a number.
requestIdstringYour own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-
callbackUrlstringWhere the result is POSTed as JSON, signed with X-MationX-Secret.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/send?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15551234567",
"message": "Hi Sarah, your order #1042 is ready for pickup today after 2 pm.",
"app": "business",
"requestId": "order-1042",
"callbackUrl": "https://example.com/mationx/callback"
}'{
"success": true,
"messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
"mode": "fire_and_forget",
"customRoute": "send",
"method": "POST",
"summary": {
"total": 1,
"running": 1,
"queued": 0,
"restarted": 0,
"queueFull": 0,
"dropped": 0,
"offline": 0,
"pending": 0,
"notListening": 0
},
"devices": [
{
"deviceId": "{deviceId}",
"handle": "phone-01",
"status": "running"
}
]
}{
"success": true,
"action": "send_message",
"status": "sent",
"requestId": "order-1042",
"deviceId": "{deviceId}",
"app": "business",
"phone": "15551234567"
}{
"success": false,
"action": "send_message",
"status": "failed",
"errorCode": "ACCOUNT_RESTRICTED",
"message": "This account is temporarily restricted from starting new chats.",
"requestId": "order-1042",
"deviceId": "{deviceId}",
"app": "business",
"phone": "15551234567"
}/p/{webhookSecret}/sendChecks whether a number is on WhatsApp, with WhatsApp itself, without sending anything. Same endpoint as sending, with validateOnly set to true.
Use it to clean a list before a campaign or to check a number a customer typed into a form.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
Body
phonestringrequiredThe number to check, in E.164 or digits.
validateOnlybooleanrequiredSet to true.
app"personal" | "business"Which WhatsApp app on the phone sends it. Default: business.
requestIdstringYour own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-
callbackUrlstringWhere the result is POSTed as JSON, signed with X-MationX-Secret.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/send?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15551234567",
"validateOnly": true,
"requestId": "lead-7731",
"callbackUrl": "https://example.com/mationx/callback"
}'{
"success": true,
"messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
"mode": "fire_and_forget",
"customRoute": "send",
"method": "POST",
"summary": {
"total": 1,
"running": 1,
"queued": 0,
"restarted": 0,
"queueFull": 0,
"dropped": 0,
"offline": 0,
"pending": 0,
"notListening": 0
},
"devices": [
{
"deviceId": "{deviceId}",
"handle": "phone-01",
"status": "running"
}
]
}{
"success": true,
"action": "validate_number",
"status": "valid",
"exists": true,
"validationOnly": true,
"requestId": "lead-7731",
"deviceId": "{deviceId}",
"phone": "15551234567"
}{
"success": true,
"action": "validate_number",
"status": "invalid",
"exists": false,
"validationOnly": true,
"requestId": "lead-7731",
"deviceId": "{deviceId}",
"phone": "15551234567"
}/p/status/{messageId}The current state of a request you sent, by the messageId from its 202 answer: the same summary and devices as the 202, as they are now. Use it to reconcile a callback you did not receive.
Note the path: /p/status/{messageId}, without your webhook secret. The messageId is an unguessable UUID and is the only key, so keep it private. Records are kept for 30 days; an unknown or expired messageId answers 404.
Path
messageIdstringrequiredThe messageId from the 202 response of the send.
curl -X GET "https://hook.mationx.cloud/p/status/6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
"summary": {
"total": 1,
"running": 0,
"queued": 0,
"restarted": 0,
"queueFull": 0,
"dropped": 0,
"offline": 0,
"pending": 0,
"notListening": 0
},
"devices": [
{
"deviceId": "{deviceId}",
"handle": "phone-01",
"status": "finished"
}
]
}{
"error": "Unknown or expired messageId"
}/p/{webhookSecret}/send-mediaSends a file with an optional caption. The phone downloads it from your URL and sends it from the WhatsApp app, the way a person attaches a file.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
Body
phonestringrequiredThe recipient, in E.164 or digits.
type"image" | "video" | "document"requiredWhat kind of file it is.
urlstringrequiredA public HTTPS URL of the file.
captionstringText sent with the file.
filenamestringThe file name the recipient sees, for documents.
app"personal" | "business"Which WhatsApp app on the phone sends it. Default: business.
requestIdstringYour own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-
callbackUrlstringWhere the result is POSTed as JSON, signed with X-MationX-Secret.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/send-media?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15551234567",
"type": "document",
"url": "https://example.com/invoices/1042.pdf",
"filename": "Invoice 1042.pdf",
"caption": "Here is your invoice for order #1042.",
"requestId": "invoice-1042",
"callbackUrl": "https://example.com/mationx/callback"
}'{
"success": true,
"messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
"mode": "fire_and_forget",
"customRoute": "send-media",
"method": "POST",
"summary": {
"total": 1,
"running": 1,
"queued": 0,
"restarted": 0,
"queueFull": 0,
"dropped": 0,
"offline": 0,
"pending": 0,
"notListening": 0
},
"devices": [
{
"deviceId": "{deviceId}",
"handle": "phone-01",
"status": "running"
}
]
}/p/{webhookSecret}/send-groupPosts a message to a WhatsApp group the number is in, or to a channel it manages.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
Body
tostringrequiredA group JID (ends in @g.us) or a channel link.
messagestringrequiredThe message text.
app"personal" | "business"Which WhatsApp app on the phone sends it. Default: business.
requestIdstringYour own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-
callbackUrlstringWhere the result is POSTed as JSON, signed with X-MationX-Secret.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/send-group?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "[email protected]",
"message": "Store update: we are open until 9 pm this Friday.",
"requestId": "group-friday",
"callbackUrl": "https://example.com/mationx/callback"
}'{
"success": true,
"messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
"mode": "fire_and_forget",
"customRoute": "send-group",
"method": "POST",
"summary": {
"total": 1,
"running": 1,
"queued": 0,
"restarted": 0,
"queueFull": 0,
"dropped": 0,
"offline": 0,
"pending": 0,
"notListening": 0
},
"devices": [
{
"deviceId": "{deviceId}",
"handle": "phone-01",
"status": "running"
}
]
}/p/{webhookSecret}/validate/bulkChecks a list of numbers in one call. The phone works through them at a safe pace and posts one callback per number, or one summary at the end.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
Body
phonesstring[]requiredThe numbers to check, in E.164 or digits.
summaryOnlybooleanSend one callback with every result at the end instead of one per number.
requestIdstringYour own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-
callbackUrlstringWhere the result is POSTed as JSON, signed with X-MationX-Secret.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/validate/bulk?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phones": [
"+15551234567",
"+15557654321",
"+447700900123"
],
"summaryOnly": true,
"requestId": "list-nov",
"callbackUrl": "https://example.com/mationx/callback"
}'{
"success": true,
"requestId": "list-nov",
"accepted": 3
}{
"success": true,
"action": "validate_bulk",
"requestId": "list-nov",
"results": [
{
"phone": "15551234567",
"exists": true
},
{
"phone": "15557654321",
"exists": false
},
{
"phone": "447700900123",
"exists": true
}
]
}/p/{webhookSecret}/devicesEvery phone on your account with its live state: online, both WhatsApp apps, the numbers on it, the warm-up day and any restriction.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/devices" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"devices": [
{
"deviceId": "{deviceId}",
"handle": "phone-01",
"online": true,
"lastSeen": "2026-11-20T09:41:12Z",
"whatsapp": {
"business": {
"state": "ready",
"version": "2.25.31.76",
"number": "15550001111"
},
"personal": {
"state": "not_installed"
}
},
"warmup": {
"status": "active",
"day": 9
},
"restriction": {
"restricted": false
}
}
]
}/p/{webhookSecret}/devices/{deviceId}One phone, the same fields as in the list.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
deviceIdstringrequiredThe device id or handle.
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/devices/phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"deviceId": "{deviceId}",
"handle": "phone-01",
"online": true,
"whatsapp": {
"business": {
"state": "restricted",
"version": "2.25.31.76",
"number": "15550001111"
}
},
"warmup": {
"status": "paused",
"day": 12,
"reason": "restricted"
},
"restriction": {
"restricted": true,
"since": "2026-11-20T07:05:00Z"
}
}/p/{webhookSecret}/devices/{deviceId}/whatsapp-stateWhat the phone sees in the WhatsApp app right now. Check it before a campaign, or let the webhook events tell you when it changes.
States: ready, update_required, setup_required, logged_out, banned, restricted, not_installed.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
deviceIdstringrequiredThe device id or handle.
Query
app"personal" | "business"Default: business.
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/devices/phone-01/whatsapp-state?app=business" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"deviceId": "{deviceId}",
"app": "business",
"state": "update_required",
"checkedAt": "2026-11-20T09:42:03Z"
}/p/{webhookSecret}/numbersThe WhatsApp numbers on your phones, read from the apps themselves, so you always know which device sends as which number.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/numbers" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"numbers": [
{
"number": "15550001111",
"app": "business",
"deviceId": "{deviceId}",
"handle": "phone-01"
},
{
"number": "15550002222",
"app": "personal",
"deviceId": "{deviceId-2}",
"handle": "phone-02"
}
]
}/p/{webhookSecret}/chats/{phone}/messagesReads the history of one chat on the phone: text, direction and date. The phone opens the chat and reads it, so the call takes a few seconds.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
phonestringrequiredThe other side of the chat, in digits.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
limitnumberHow many of the latest messages. Default 20.
from"them" | "us"Only messages from one side.
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/chats/15551234567/messages?deviceId=phone-01&limit=20" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"phone": "15551234567",
"app": "business",
"messages": [
{
"direction": "out",
"text": "Hi Sarah, your order #1042 is ready for pickup today after 2 pm.",
"date": "2026-11-20T09:12:00Z"
},
{
"direction": "in",
"text": "Great, can my husband pick it up?",
"date": "2026-11-20T09:19:00Z"
}
]
}/p/{webhookSecret}/callsPlaces a WhatsApp voice call from the phone, and ends it with POST /p/{webhookSecret}/calls/{callId}/hangup. Incoming calls arrive as the call.received event and can be answered the same way.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
Query
deviceIdstringrequiredThe MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.
Body
phonestringrequiredWho to call.
durationSecondsnumberHang up on its own after this many seconds.
app"personal" | "business"Which WhatsApp app on the phone sends it. Default: business.
callbackUrlstringWhere the result is POSTed as JSON, signed with X-MationX-Secret.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/calls?deviceId=phone-01" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15551234567",
"durationSeconds": 45,
"callbackUrl": "https://example.com/mationx/callback"
}'{
"success": true,
"callId": "call_8d2f41",
"status": "ringing"
}/p/{webhookSecret}/warmup/{deviceId}/pausePause a number's warm-up (for example during a campaign) and resume it with /resume. GET /p/{webhookSecret}/warmup/status returns every number's warm-up day and state.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
deviceIdstringrequiredThe device id or handle.
Body
untilstringISO 8601 time to resume on its own.
curl -X POST "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/warmup/phone-01/pause" \
-H "Authorization: Bearer $MATIONX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"until": "2026-11-22T08:00:00Z"
}'{
"deviceId": "{deviceId}",
"warmup": {
"status": "paused",
"day": 9,
"resumesAt": "2026-11-22T08:00:00Z"
}
}/p/{webhookSecret}/messages/{messageId}Where the app shows it, the state of a sent message: sent, delivered or read, read from the ticks in the chat.
Path
webhookSecretstringrequiredYour webhook secret. It is part of the URL and identifies your account.
messageIdstringrequiredThe messageId returned when you sent it.
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/messages/6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24" \
-H "Authorization: Bearer $MATIONX_API_TOKEN"{
"messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
"requestId": "order-1042",
"status": "read",
"updatedAt": "2026-11-20T09:15:40Z"
}Webhooks
Callbacks
When a send or a validation finishes, the phone POSTs the result as JSON to the callbackUrl of that request, with your requestId in it so you can match it to your own record. Every callback carries the header X-MationX-Secret with your callback secret.
Callbacks are sent once: one POST from the phone, with a 20 second timeout, and no retry. Make your endpoint return 2xx quickly and use the status endpoint to reconcile anything you missed, by the messageId you stored with your requestId.
success is true when the action worked, action says what it was (send_message or validate_number), and a failed callback adds errorCode and a readable message.
X-MationX-Secret: {callbackSecret}
Content-Type: application/json
{
"success": true,
"action": "send_message",
"status": "sent",
"requestId": "order-1042",
"deviceId": "{deviceId}",
"app": "business",
"phone": "15551234567"
}Beyond the results of your own requests, the phones notice what happens to your numbers and can tell your system right away: a message coming in, a call, a restriction, a ban, a phone going offline, an expired WhatsApp version. Choose the events you want and the URL they go to; each one is a POST with the same X-MationX-Secret header and this envelope:
send.resultThe result of every send and validation at one URL. Today the same payload arrives live as the callback of each request.
{
"event": "send.result",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"success": true,
"action": "send_message",
"status": "sent",
"requestId": "order-1042",
"phone": "15551234567"
}
}message.receivedA message came in on one of your numbers.
{
"event": "message.received",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"from": "15551234567",
"text": "Great, can my husband pick it up?",
"app": "business"
}
}call.receivedSomeone is calling one of your numbers on WhatsApp.
{
"event": "call.received",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"from": "15551234567",
"app": "business"
}
}account.restrictedWhatsApp restricted the account from starting new chats. Stop sending from it.
{
"event": "account.restricted",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"app": "business",
"number": "15550001111"
}
}account.restriction_liftedWhatsApp's no longer restricted notice arrived. The number can send again.
{
"event": "account.restriction_lifted",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"app": "business",
"number": "15550001111"
}
}account.bannedThe account is banned.
{
"event": "account.banned",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"app": "business",
"number": "15550001111"
}
}device.offlineThe phone lost its connection to MationX. Requests for it are not kept: send them to another phone.
{
"event": "device.offline",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"lastSeen": "2026-11-20T09:41:12Z"
}
}device.onlineThe phone is back and takes requests again.
{
"event": "device.online",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"since": "2026-11-20T09:52:30Z"
}
}whatsapp.update_requiredThe WhatsApp version on the phone has expired and must be updated before it can send.
{
"event": "whatsapp.update_required",
"deviceId": "{deviceId}",
"handle": "phone-01",
"timestamp": "2026-11-20T09:19:04Z",
"data": {
"app": "business",
"version": "2.25.21.80"
}
}Check the X-MationX-Secret header on every callback and event before you trust it, with a constant-time comparison, and reject anything without it. Keep the handler fast: answer 2xx first and do the slow work after, because a callback that times out is not sent again.
Make the handler idempotent: store the requestId values you have handled and skip one you have already seen.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const app = express();
app.use(express.json());
const SECRET = Buffer.from(process.env.MATIONX_CALLBACK_SECRET);
app.post("/mationx/callback", (req, res) => {
const got = Buffer.from(req.get("X-MationX-Secret") || "");
if (got.length !== SECRET.length || !timingSafeEqual(got, SECRET)) {
return res.sendStatus(401);
}
const e = req.body;
if (e.action === "send_message" && e.status === "failed") {
// e.errorCode: NUMBER_NOT_REGISTERED, ACCOUNT_RESTRICTED, ...
}
res.sendStatus(200);
});Guides
Errors about a message come in the callback with an errorCode. A request that never reached a phone shows in the summary of the 202 and of the status endpoint. Errors about the request itself come back as the HTTP status.
NUMBER_NOT_REGISTEREDCallbackThe number is not on WhatsApp. This is checked with WhatsApp directly. Remove it from the list.
ACCOUNT_RESTRICTEDCallbackWhatsApp has temporarily restricted the sending account, so it cannot start new chats. Skip that phone until the restriction clears, usually after a few hours; we recommend a 48 hour pause.
ACCOUNT_BANNEDCallbackThe sending account is banned. Take the number out of rotation.
MESSAGE_SEND_FAILEDCallbackWhatsApp did not complete the action, for example a timeout or an unexpected screen. Safe to retry later.
QUEUE_FULLSummaryThe phone already had 5 requests waiting. The request is not run and no callback is sent; it shows in summary.queueFull and in that device's status. Retry it later or on another phone.
offlineSummaryThe target phone was offline at that moment. The request is not kept for later and no callback is sent. Retry it on another phone.
202HTTPAccepted. If no phone is listening on the route, the body says so: "Webhook accepted, but no device is currently listening on this route."
400HTTP{"error":"Project is inactive"}: the automation behind the route is switched off.
401HTTP{"error":"Unauthorized: Invalid or missing Bearer token"}
404HTTP{"error":"Webhook route not found"} for an unknown webhook, or "No listening device matches ..." when the deviceId is wrong or that phone is not running the project.
429HTTPMore than 50 requests a second from one IP. The body is plain text, and the RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers say when to try again.
500HTTP{"error":"Internal server error"}. Retry later.
A new number that starts sending at full volume on day one is the fastest way to lose it. Every number on MationX warms up first, on its own, with nothing to call:
- Phones warm up in pods: three sessions a day, with partners that rotate.
- The numbers chat with each other, reply and call, the way new users do.
- Activity grows a little every day on a daily ramp.
- Bans and temporary restrictions are watched: the phone is paused, then resumed when it clears.
Your sends and the warm-up share the phone in turns, so a campaign never collides with a warm-up session. Warm-up status and pause/resume are available as endpoints on request.
Restrictions come from one-way messages, blocks and reports, not from the API. These are the volumes that keep numbers healthy, per number and counting only new chats; replies in existing chats do not count.
Week 1
20 to 30 new chats a day
At most about 10 an hour.
Week 2
40 to 50 a day
If the first week went quietly.
Week 3 on
60 to 80 a day
When people reply.
- Make the first message personal, and leave links out of it.
- After ACCOUNT_RESTRICTED, pause that number for 48 hours.
- WhatsApp is rolling out a monthly limit on new chats that get no reply; the Business app has shown 300.
- Spread a campaign over many numbers rather than pushing one number harder.
Endpoints for your setup
Built around your CRM and workflow
Endpoints, fields and webhooks are not fixed: we adapt existing ones or build new ones per client, to fit their CRM and workflow. Talk to us and we'll set it up for you.