MationX

WhatsApp APIDocumentation

WhatsApp API documentation

Send and receive WhatsApp messages through the real WhatsApp app on real Android phones. One REST endpoint, callbacks for every result and webhooks for everything that happens on the phones.

Base URLhttps://hook.mationx.cloud
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.
Every request
# 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. 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. 2

    Send your first message

    POST to the send endpoint with the recipient and the text. The API answers 202 at once.

  3. 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.

Send a message
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.

Headers
Authorization: Bearer {apiToken}
Content-Type: application/json

# the secret is in the path
POST /p/{webhookSecret}/send?deviceId=phone-01

The 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.
Over the limit
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.

Endpoints

Live
POST/p/{webhookSecret}/send

Sends 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

Query

  • deviceIdstringrequired

    The MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.

Body

  • phonestringrequired

    The recipient, in E.164 or digits. "+" and spaces are stripped.

  • messagestring

    The message text.

  • app"personal" | "business"

    Which WhatsApp app on the phone sends it. Default: business.

  • validateOnlyboolean

    Only check whether the number is on WhatsApp. Nothing is sent. See Validate a number.

  • requestIdstring

    Your own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-

  • callbackUrlstring

    Where the result is POSTed as JSON, signed with X-MationX-Secret.

Send a message
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"
  }'
202 Accepted
{
  "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"
    }
  ]
}
Callback: sent
{
  "success": true,
  "action": "send_message",
  "status": "sent",
  "requestId": "order-1042",
  "deviceId": "{deviceId}",
  "app": "business",
  "phone": "15551234567"
}
Callback: failed
{
  "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"
}
POST/p/{webhookSecret}/send

Checks 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

Query

  • deviceIdstringrequired

    The MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.

Body

  • phonestringrequired

    The number to check, in E.164 or digits.

  • validateOnlybooleanrequired

    Set to true.

  • app"personal" | "business"

    Which WhatsApp app on the phone sends it. Default: business.

  • requestIdstring

    Your own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-

  • callbackUrlstring

    Where the result is POSTed as JSON, signed with X-MationX-Secret.

Validate a number
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"
  }'
202 Accepted
{
  "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"
    }
  ]
}
Callback: on WhatsApp
{
  "success": true,
  "action": "validate_number",
  "status": "valid",
  "exists": true,
  "validationOnly": true,
  "requestId": "lead-7731",
  "deviceId": "{deviceId}",
  "phone": "15551234567"
}
Callback: not on WhatsApp
{
  "success": true,
  "action": "validate_number",
  "status": "invalid",
  "exists": false,
  "validationOnly": true,
  "requestId": "lead-7731",
  "deviceId": "{deviceId}",
  "phone": "15551234567"
}
GET/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

  • messageIdstringrequired

    The messageId from the 202 response of the send.

Get a request's status
curl -X GET "https://hook.mationx.cloud/p/status/6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "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"
    }
  ]
}
404 Not Found
{
  "error": "Unknown or expired messageId"
}
POST/p/{webhookSecret}/send-media

Sends 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

Query

  • deviceIdstringrequired

    The MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.

Body

  • phonestringrequired

    The recipient, in E.164 or digits.

  • type"image" | "video" | "document"required

    What kind of file it is.

  • urlstringrequired

    A public HTTPS URL of the file.

  • captionstring

    Text sent with the file.

  • filenamestring

    The file name the recipient sees, for documents.

  • app"personal" | "business"

    Which WhatsApp app on the phone sends it. Default: business.

  • requestIdstring

    Your own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-

  • callbackUrlstring

    Where the result is POSTed as JSON, signed with X-MationX-Secret.

Send an image, video or document
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"
  }'
202 Accepted
{
  "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"
    }
  ]
}
POST/p/{webhookSecret}/send-group

Posts a message to a WhatsApp group the number is in, or to a channel it manages.

Path

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

Query

  • deviceIdstringrequired

    The MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.

Body

  • tostringrequired

    A group JID (ends in @g.us) or a channel link.

  • messagestringrequired

    The message text.

  • app"personal" | "business"

    Which WhatsApp app on the phone sends it. Default: business.

  • requestIdstring

    Your own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-

  • callbackUrlstring

    Where the result is POSTed as JSON, signed with X-MationX-Secret.

Send to a group or channel
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"
  }'
202 Accepted
{
  "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"
    }
  ]
}
POST/p/{webhookSecret}/validate/bulk

Checks 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

Query

  • deviceIdstringrequired

    The 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[]required

    The numbers to check, in E.164 or digits.

  • summaryOnlyboolean

    Send one callback with every result at the end instead of one per number.

  • requestIdstring

    Your own ID, returned in the callback. Allowed characters: A-Za-z0-9_.:-

  • callbackUrlstring

    Where the result is POSTed as JSON, signed with X-MationX-Secret.

Validate numbers in bulk
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"
  }'
202 Accepted
{
  "success": true,
  "requestId": "list-nov",
  "accepted": 3
}
Callback: summary
{
  "success": true,
  "action": "validate_bulk",
  "requestId": "list-nov",
  "results": [
    {
      "phone": "15551234567",
      "exists": true
    },
    {
      "phone": "15557654321",
      "exists": false
    },
    {
      "phone": "447700900123",
      "exists": true
    }
  ]
}
Available
GET/p/{webhookSecret}/devices

Every phone on your account with its live state: online, both WhatsApp apps, the numbers on it, the warm-up day and any restriction.

Path

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

List devices
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/devices" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "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
      }
    }
  ]
}
Available
GET/p/{webhookSecret}/devices/{deviceId}

One phone, the same fields as in the list.

Path

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

  • deviceIdstringrequired

    The device id or handle.

Get a device
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/devices/phone-01" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "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"
  }
}
GET/p/{webhookSecret}/devices/{deviceId}/whatsapp-state

What 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

  • deviceIdstringrequired

    The device id or handle.

Query

  • app"personal" | "business"

    Default: business.

Check WhatsApp state
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/devices/phone-01/whatsapp-state?app=business" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "deviceId": "{deviceId}",
  "app": "business",
  "state": "update_required",
  "checkedAt": "2026-11-20T09:42:03Z"
}
GET/p/{webhookSecret}/numbers

The WhatsApp numbers on your phones, read from the apps themselves, so you always know which device sends as which number.

Path

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

List your numbers
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/numbers" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "numbers": [
    {
      "number": "15550001111",
      "app": "business",
      "deviceId": "{deviceId}",
      "handle": "phone-01"
    },
    {
      "number": "15550002222",
      "app": "personal",
      "deviceId": "{deviceId-2}",
      "handle": "phone-02"
    }
  ]
}
Available
GET/p/{webhookSecret}/chats/{phone}/messages

Reads 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

  • phonestringrequired

    The other side of the chat, in digits.

Query

  • deviceIdstringrequired

    The MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.

  • limitnumber

    How many of the latest messages. Default 20.

  • from"them" | "us"

    Only messages from one side.

Read a chat
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/chats/15551234567/messages?deviceId=phone-01&limit=20" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "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"
    }
  ]
}
POST/p/{webhookSecret}/calls

Places 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

Query

  • deviceIdstringrequired

    The MationX device id or handle of the phone that does the work. One request targets exactly one phone; an unknown device returns 404.

Body

  • phonestringrequired

    Who to call.

  • durationSecondsnumber

    Hang up on its own after this many seconds.

  • app"personal" | "business"

    Which WhatsApp app on the phone sends it. Default: business.

  • callbackUrlstring

    Where the result is POSTed as JSON, signed with X-MationX-Secret.

Start and end a call
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"
  }'
202 Accepted
{
  "success": true,
  "callId": "call_8d2f41",
  "status": "ringing"
}
POST/p/{webhookSecret}/warmup/{deviceId}/pause

Pause 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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

  • deviceIdstringrequired

    The device id or handle.

Body

  • untilstring

    ISO 8601 time to resume on its own.

Warm-up status, pause and resume
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"
  }'
200 OK
{
  "deviceId": "{deviceId}",
  "warmup": {
    "status": "paused",
    "day": 9,
    "resumesAt": "2026-11-22T08:00:00Z"
  }
}
GET/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

  • webhookSecretstringrequired

    Your webhook secret. It is part of the URL and identifies your account.

  • messageIdstringrequired

    The messageId returned when you sent it.

Delivered and read receipts
curl -X GET "https://hook.mationx.cloud/p/$WEBHOOK_SECRET/messages/6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24" \
  -H "Authorization: Bearer $MATIONX_API_TOKEN"
200 OK
{
  "messageId": "6f1c2e3a-8b4d-4c1e-9a7f-2d5e8c0b1a24",
  "requestId": "order-1042",
  "status": "read",
  "updatedAt": "2026-11-20T09:15:40Z"
}

Webhooks

Callbacks

Live

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.

POST {callbackUrl}
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.result

The result of every send and validation at one URL. Today the same payload arrives live as the callback of each request.

Available
Payload
{
  "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.received

A message came in on one of your numbers.

Available
Payload
{
  "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.received

Someone is calling one of your numbers on WhatsApp.

Available
Payload
{
  "event": "call.received",
  "deviceId": "{deviceId}",
  "handle": "phone-01",
  "timestamp": "2026-11-20T09:19:04Z",
  "data": {
    "from": "15551234567",
    "app": "business"
  }
}
account.restricted

WhatsApp restricted the account from starting new chats. Stop sending from it.

Available
Payload
{
  "event": "account.restricted",
  "deviceId": "{deviceId}",
  "handle": "phone-01",
  "timestamp": "2026-11-20T09:19:04Z",
  "data": {
    "app": "business",
    "number": "15550001111"
  }
}
account.restriction_lifted

WhatsApp's no longer restricted notice arrived. The number can send again.

Available
Payload
{
  "event": "account.restriction_lifted",
  "deviceId": "{deviceId}",
  "handle": "phone-01",
  "timestamp": "2026-11-20T09:19:04Z",
  "data": {
    "app": "business",
    "number": "15550001111"
  }
}
account.banned

The account is banned.

Available
Payload
{
  "event": "account.banned",
  "deviceId": "{deviceId}",
  "handle": "phone-01",
  "timestamp": "2026-11-20T09:19:04Z",
  "data": {
    "app": "business",
    "number": "15550001111"
  }
}
device.offline

The phone lost its connection to MationX. Requests for it are not kept: send them to another phone.

Available
Payload
{
  "event": "device.offline",
  "deviceId": "{deviceId}",
  "handle": "phone-01",
  "timestamp": "2026-11-20T09:19:04Z",
  "data": {
    "lastSeen": "2026-11-20T09:41:12Z"
  }
}
device.online

The phone is back and takes requests again.

Available
Payload
{
  "event": "device.online",
  "deviceId": "{deviceId}",
  "handle": "phone-01",
  "timestamp": "2026-11-20T09:19:04Z",
  "data": {
    "since": "2026-11-20T09:52:30Z"
  }
}
whatsapp.update_required

The WhatsApp version on the phone has expired and must be updated before it can send.

Available
Payload
{
  "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.

Verify the secret
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_REGISTEREDCallback

    The number is not on WhatsApp. This is checked with WhatsApp directly. Remove it from the list.

  • ACCOUNT_RESTRICTEDCallback

    WhatsApp 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_BANNEDCallback

    The sending account is banned. Take the number out of rotation.

  • MESSAGE_SEND_FAILEDCallback

    WhatsApp did not complete the action, for example a timeout or an unexpected screen. Safe to retry later.

  • QUEUE_FULLSummary

    The 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.

  • offlineSummary

    The target phone was offline at that moment. The request is not kept for later and no callback is sent. Retry it on another phone.

  • 202HTTP

    Accepted. 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.

  • 429HTTP

    More 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.

CodeWhereWhat it means and what to do
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.

Day 6 of 14+1 contactCall 0:48Quiet 23–07

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.

WhatsApp is a trademark of Meta Platforms, Inc. MationX is not affiliated with Meta.