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.

Before you can send messages or read chats, the WhatsApp Web client must be running and authenticated. POST /api/auth/start starts that process by launching a Chrome browser instance, connecting it to WhatsApp Web, and returning the current client state. Once Chrome is up, the server will emit a QR code (visible at GET /qr) or complete automatically if saved credentials already exist in auth_dir.

​
Endpoint

POST /api/auth/start
No request body is required.

​
Behavior

  • If the client is already running or fully ready, the call returns immediately with the current state — it is safe to call multiple times.
  • If initialization is already in progress (another concurrent call), the request waits for that in-flight initialization to finish before returning.
  • If saved credentials exist from a previous session, Chrome may authenticate silently without showing a QR code and the state will transition directly from starting → authenticated → ready.

​
Response Fields

The response is the same status object returned by GET /api/status.
​
state
string
required
Lifecycle state immediately after the call. Typically starting or qr for a fresh client, or ready if credentials were restored from disk.
​
ready
boolean
required
true only if Chrome has fully connected and the session is usable. Most first-time calls will return false here while Chrome starts up.
​
authenticated
boolean
required
Mirrors ready.
​
auth_dir
string
required
Path to the directory where session credentials are stored.
​
chrome_executable
string
required
Path to the Chrome binary being used.
​
headless
boolean
required
Whether Chrome is running in headless mode.
​
has_qr
boolean
required
true when a QR code is ready to scan at GET /qr.
​
last_error
string | null
required
Last error message, or null.
​
account
object | null
required
Account info when authenticated, null otherwise.

​
Example Request

curl -X POST http://127.0.0.1:8790/api/auth/start

​
Example Response

A typical response immediately after calling the endpoint for the first time, while Chrome is still loading: 
{
  "state": "starting",
  "ready": false,
  "authenticated": false,
  "auth_dir": "/home/user/whatsapp-mcp-api/.wwebjs_auth",
  "chrome_executable": "/usr/bin/google-chrome",
  "headless": false,
  "has_qr": false,
  "last_error": null,
  "account": null
}
After Chrome has loaded and generated the QR code, GET /api/status will return state: "qr" and has_qr: true.
You do not need to call /api/auth/start manually before using /api/pairing-code or any messaging endpoint. Those endpoints call start() internally (and ensureReady()) — but calling it explicitly lets you pre-warm Chrome and monitor progress via GET /api/status polling before issuing your first real request.

Build docs developers (and LLMs) love

Get started for freeTalk to us