WhatsApp MCP API authenticates by registering itself as a Linked Device on your personal WhatsApp account — the same mechanism used by the official WhatsApp Web and WhatsApp Desktop apps. There are no passwords, API tokens, or third-party credentials involved. The server uses whatsapp-web.js to drive a local Chrome or Chromium browser that connects directly to WhatsApp’s infrastructure, and your session is stored entirely on your own machine.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.
How Authentication Works
The full pairing flow from cold start to ready state looks like this:-
Chrome launches — On first start (or after
POST /api/auth/start), the server spawns a Chrome or Chromium browser via Puppeteer using the executable atWHATSAPP_CHROME_EXECUTABLE. The client state moves tostarting. -
WhatsApp Web loads — Chrome opens
web.whatsapp.cominside the managed browser profile stored in.wwebjs_auth/session-default. If no saved session exists, WhatsApp Web prompts for device linking. -
User pairs the device — You have two options to complete the link (see Two Pairing Methods below). Once WhatsApp receives the pairing signal the client state advances to
authenticated. -
Session saved locally — After a successful pair, whatsapp-web.js persists the full Chrome user profile — including WhatsApp Web’s IndexedDB encryption keys — inside
.wwebjs_auth/session-default. The client state then moves toready, the pending QR code is cleared, and the account info (wid,pushname,platform) is populated fromclient.info. -
Automatic reconnect on restart — On every subsequent server start, Chrome loads the saved profile and reconnects to WhatsApp without requiring a new QR scan or pairing code. The state transitions directly from
startingtoauthenticatedtoready.
Authentication States
The server tracks astate field that is returned by GET /api/status. Each value represents a distinct phase of the connection lifecycle:
| State | Meaning |
|---|---|
stopped | No WhatsApp client is running. This is the initial state and the state after a successful logout. |
starting | Client is initializing — Chrome is launching and WhatsApp Web is loading. |
qr | A QR code has been received from WhatsApp Web and is waiting to be scanned. |
authenticated | Pairing completed; the session is being loaded into the client. |
ready | Fully connected and authenticated. All API calls are available. |
auth_failure | Authentication failed. The last_error field contains the reason. |
disconnected | WhatsApp Web disconnected after a previously ready session. |
GET /api/status to track progress and determine when the client is ready to accept API calls.
Two Pairing Methods
WhatsApp MCP API supports both pairing methods that WhatsApp offers for Linked Devices:Phone-Number Pairing Code (Recommended for Headless)
POST /api/pairing-code accepts your phone number and returns an 8-digit numeric code. You then enter this code directly in the WhatsApp mobile app under Linked Devices → Link with phone number instead. No browser window or camera is required, which makes this the preferred method for server, CI, or headless environments.
QR Code (Browser-Based)
GET /qr serves an HTML page that renders the current QR code as an image and auto-refreshes every 5 seconds. Open this URL in any browser while the server is in the qr state, then scan the code with your phone’s WhatsApp camera under Linked Devices → Link a device.
Pairing Code
Request a numeric code via
POST /api/pairing-code and link without a QR scan.Session Management
Learn how sessions are stored in
.wwebjs_auth and how to back up or reset them.