Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jihvijhojhviihogyuvi/whatsapp-api/llms.txt

Use this file to discover all available pages before exploring further.

Phone-number pairing lets you link the WhatsApp MCP API server to your WhatsApp account by entering a short numeric code in the mobile app — no QR code, no camera, and no visible browser window required. This makes it the go-to method for headless servers, remote machines, and automated provisioning scripts.
Prerequisites: The server must be running (npm start) and Chrome or Chromium must be reachable at the path configured in WHATSAPP_CHROME_EXECUTABLE. The client must not already be in the ready state — if it is, the endpoint returns an already_authenticated response instead of a new code.

​
Step-by-step Process

1

Start the server

From the whatsapp-mcp-api/ directory, start the server:
npm start
The server starts on http://127.0.0.1:8790 by default. Chrome is not launched yet — that happens on the next step.
2

Initialize the WhatsApp client (optional)

Triggering auth start explicitly launches Chrome and begins loading WhatsApp Web. The pairing code endpoint will do this automatically if needed, but you can start it early:
curl -X POST http://127.0.0.1:8790/api/auth/start
Wait until GET /api/status reports state: "qr" or state: "starting" before proceeding — this confirms Chrome is up and WhatsApp Web has made contact.
3

Request the pairing code

Call POST /api/pairing-code with your phone number. The server will request a numeric code from WhatsApp on your behalf:
curl -X POST http://127.0.0.1:8790/api/pairing-code \
  -H "content-type: application/json" \
  -d '{"phone_number": "15551234567"}'
A successful response looks like this:
{
  "already_authenticated": false,
  "phone_number": "15551234567",
  "code": "12345678",
  "instructions": "WhatsApp -> Linked devices -> Link a device -> Link with phone number instead"
}
Note the value of "code" — you will enter this on your phone in the next step.
4

Enter the code on your phone

Open WhatsApp on your mobile device and navigate to:Settings → Linked Devices → Link a Device → Link with phone number insteadType the numeric code exactly as returned in the "code" field. WhatsApp will verify the code and complete the device link.
5

Wait for the ready state

After entering the code, poll GET /api/status until the client reaches the ready state:
curl http://127.0.0.1:8790/api/status

{
  "state": "ready",
  "ready": true,
  "authenticated": true
}
Once state is "ready", all messaging and chat APIs are available.

​
Request

Endpoint: POST /api/pairing-code
​
phone_number
string
required
The phone number associated with your WhatsApp account. Must include the country code. Non-digit characters (spaces, dashes, +) are stripped automatically. The resulting digit string must be between 8 and 15 characters long.
Example request: 
curl -X POST http://127.0.0.1:8790/api/pairing-code \
  -H "content-type: application/json" \
  -d '{"phone_number": "15551234567"}'

​
Response

​
Not yet authenticated

When the server is in the qr or starting state and a new pairing code is successfully generated:
​
already_authenticated
boolean
false — the server is not yet linked.
​
phone_number
string
The normalized (digits-only) phone number the code was issued for.
​
code
string
The numeric pairing code to enter in the WhatsApp app.
​
instructions
string
Human-readable navigation path for entering the code on the phone.
{
  "already_authenticated": false,
  "phone_number": "15551234567",
  "code": "12345678",
  "instructions": "WhatsApp -> Linked devices -> Link a device -> Link with phone number instead"
}

​
Already authenticated

When the client is already in the ready state, no new code is generated:
​
already_authenticated
boolean
true — the server already has an active WhatsApp session.
​
code
null
Always null when already authenticated.
​
status
object
The full status object from GET /api/status, including state, account, and auth_dir.
{
  "already_authenticated": true,
  "code": null,
  "status": {
    "state": "ready",
    "ready": true,
    "authenticated": true,
    "auth_dir": "/path/to/.wwebjs_auth",
    "account": {
      "wid": "15551234567@c.us",
      "pushname": "Your Name",
      "platform": "iphone"
    }
  }
}

​
Phone Number Format

The server normalizes phone numbers through the normalizePhone function: all non-digit characters are stripped first, then the length is validated. Valid inputs include:
FormatInput exampleNormalized
Digits only (US)1555123456715551234567
E.164 (US)+1555123456715551234567
Digits only (UK)447911123456447911123456
E.164 (UK)+447911123456447911123456
The country code is required — do not omit the leading country digits. The final digit string must be between 8 and 15 characters; anything outside that range returns an error.
Pairing codes are valid for 3 minutes (180 seconds). If you don’t enter the code in time or WhatsApp rejects it, call POST /api/pairing-code again with the same phone number to receive a fresh code.

Build docs developers (and LLMs) love

Get started for freeTalk to us