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.

This guide walks you through everything you need to get WhatsApp MCP API running locally — from cloning the repository to sending your very first WhatsApp message via the REST API. By the end, your server will be listening on http://127.0.0.1:8790, your phone will be linked, and you’ll have confirmed a successful message send.
Prerequisites before you begin:
  • Node.js >= 20 — check with node --version
  • Google Chrome installed on the machine running the server (the server drives Chrome via Puppeteer)
  • A WhatsApp-registered phone number you can access to enter the pairing code
1

Clone the repository

Clone the WhatsApp MCP API repository from GitHub:
git clone https://github.com/jihvijhojhviihogyuvi/whatsapp-api.git
2

Install dependencies

Navigate into the server directory and install the Node.js dependencies:
cd whatsapp-api/whatsapp-mcp-api && npm install
This installs whatsapp-web.js, qrcode, qrcode-terminal, and all other required packages listed in package.json.
3

Start the server

Start the server with the default configuration:
npm start
The server starts and binds to http://127.0.0.1:8790. You will see output similar to:
WhatsApp MCP API listening on http://127.0.0.1:8790
MCP endpoint: http://127.0.0.1:8790/mcp
Chrome executable: C:\Program Files\Google\Chrome\Application\chrome.exe
WhatsApp Web auth directory: .../.wwebjs_auth
Chrome will open in the background so it can handle the WhatsApp Web session.
4

Request a pairing code

With the server running, request a Linked Devices pairing code for your phone number. Include the full country code (no + prefix, no spaces or dashes):
curl -X POST http://127.0.0.1:8790/api/pairing-code \
  -H "content-type: application/json" \
  -d '{"phone_number":"15551234567"}'
A successful response returns a pairing code, for example:
{
  "already_authenticated": false,
  "phone_number": "15551234567",
  "code": "ABCD-1234",
  "instructions": "WhatsApp -> Linked devices -> Link a device -> Link with phone number instead"
}
​
phone_number
string
required
Your WhatsApp phone number including country code, digits only. Example: 15551234567 for a US number. No +, spaces, or dashes.
5

Link your phone

Open WhatsApp on your phone and navigate to:
Settings → Linked Devices → Link a Device → Link with phone number instead
Enter the pairing code returned in the previous step. WhatsApp will confirm the device is linked within a few seconds, and the server logs will show:
WhatsApp Web authenticated.
WhatsApp Web client ready.
6

Send your first message

With the session ready, send a text message to any WhatsApp number (include the full country code):
curl -X POST http://127.0.0.1:8790/api/send \
  -H "content-type: application/json" \
  -d '{"phone_number":"15551234567","message":"hello from api"}'
A successful response confirms delivery:
{
  "ok": true,
  "to": "15551234567",
  "chat_id": "15551234567@c.us",
  "message_id": "true_15551234567@c.us_XXXXXXXXXXXXXXXX",
  "timestamp": "2024-11-05T12:00:00.000Z"
}
​
phone_number
string
required
Recipient’s WhatsApp phone number with country code, digits only.
​
message
string
required
The text message body to send.
Once paired, the WhatsApp session is saved in .wwebjs_auth/session-default at the repository root (i.e. whatsapp-api/.wwebjs_auth/session-default). On every subsequent npm start, the server restores the session automatically — no re-pairing required. Keep this directory intact to preserve your linked-device credentials.
To verify the server is running and check the current WhatsApp connection state at any time, call the root health endpoint:
curl http://127.0.0.1:8790/
The response includes ok: true, the MCP endpoint URL, and a full status object describing the WhatsApp client state (e.g. ready, qr, authenticated, disconnected).

Build docs developers (and LLMs) love

Get started for freeTalk to us