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.

The WhatsApp MCP API is a local Node.js HTTP server that exposes WhatsApp Web messaging through a simple REST interface. It runs on your machine and communicates with a Chrome browser instance via whatsapp-web.js. Because the server is local, no API keys or authentication tokens are required — every endpoint is open on localhost. All responses include access-control-allow-origin: * CORS headers so you can call the API from any browser or local tool.

​
Base URL

http://127.0.0.1:8790
The host and port are configurable through environment variables:
VariableDefaultDescription
WHATSAPP_MCP_HOST127.0.0.1Bind address for the HTTP server
WHATSAPP_MCP_PORT8790TCP port for the HTTP server
WHATSAPP_AUTH_DIR../.wwebjs_authDirectory where session credentials are stored
WHATSAPP_CHROME_EXECUTABLEC:\Program Files\Google\Chrome\Application\chrome.exePath to the Chrome binary
WHATSAPP_HEADLESSfalseSet to true to run Chrome without a visible window

​
Endpoint Summary

MethodPathDescription
GET/Health check with server info and WhatsApp status
GET/healthAlias for GET /
GET/api/statusWhatsApp client connection state
POST/api/auth/startLaunch Chrome and start the authentication flow
POST/api/pairing-codeRequest a phone-number pairing code
POST/api/sendSend a WhatsApp text message
GET/api/chatsList recent chats sorted by timestamp
GET/api/messagesFetch messages from a chat (query-param variant)
POST/api/messagesFetch messages from a chat (JSON body variant)
POST/api/logoutEnd the WhatsApp session and stop Chrome
GET/qrAuto-refreshing HTML page displaying the auth QR code

​
Request Format

POST endpoints expect a JSON body. Set the Content-Type header to application/json: 
curl -X POST http://127.0.0.1:8790/api/send \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "15551234567", "message": "Hello!"}'
GET endpoints accept parameters as URL query strings and require no body.

​
Response Format

All REST endpoints return application/json with pretty-printed output (2-space indentation), except GET /qr which returns an HTML page. Most successful responses include an ok: true field at the top level — the exception is GET /api/status, which returns the status object directly without an ok wrapper. Example of a wrapped response: 
{
  "ok": true,
  "count": 3,
  "chats": []
}

​
Error Responses

When a request fails, the server returns a JSON error envelope modelled on JSON-RPC 2.0: 
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "phone_number must include country code and contain 8-15 digits"
  }
}
HTTP statusMeaning
400Bad input — invalid JSON body or failed parameter validation (error code -32602)
404Path not found
500Server-side error — WhatsApp not ready, Chrome crash, send failure, etc. (error code -32000)

​
Phone Number Format

All endpoints that accept a phone_number parameter normalize the value automatically:
  1. All non-digit characters are stripped (spaces, dashes, parentheses, + signs).
  2. The resulting string must be 8–15 digits including the country code.
+1 (555) 123-4567  →  15551234567   ✅
+44 7700 900123    →  447700900123  ✅
555-1234           →  5551234       ❌  too short, no country code
Pass numbers in plain digit form or E.164 format — both work: 
"15551234567"     plain digits
"+15551234567"    E.164 (the + is stripped automatically)

​
Pages in This Section

GET /api/status

Check the current WhatsApp client state, connection status, and account info.

POST /api/auth/start

Launch Chrome and start the WhatsApp Web authentication flow.

POST /api/send

Send a text message to any WhatsApp number.

GET /api/chats

List recent chats sorted by timestamp with unread counts.

GET /api/messages

Read recent messages from a chat by phone number.

POST /api/logout

End the WhatsApp session and reset the server state.

GET /qr

Open the browser-based QR authentication page.

Build docs developers (and LLMs) love

Get started for freeTalk to us