Send WhatsApp messages from your app, without Wati or Interakt

OpenWA on GitHub↗ (opens in a new tab)Free · MIT licence

Open a terminal in the folder where you keep your projects and run these. They’re the same commands as the Local Dev tab of the quick start on www.open-wa.org.

git clone https://github.com/rmyndharis/OpenWA.gitcd OpenWAnpm installnpm run dev

npm install also downloads a copy of Chrome. OpenWA runs WhatsApp Web inside it, out of sight, and that is how it talks to WhatsApp. It’s why the first install takes a few minutes.

When the logs settle, three addresses are live:

Open http://localhost:2886 in your browser. The dashboard asks for an API Key.

OpenWA saved that key in a file inside the project. In your second terminal, from the OpenWA folder, print it:

cat data/.api-key

In Windows Command Prompt, it’s type data\.api-key. Copy the whole line, paste it into the dashboard and press Connect.

1. In the dashboard, open Sessions and click New Session.
2. Name it, for example my-app (lowercase letters, numbers and hyphens only), and click Create.
3. Click Start on the new session, and a QR code opens. Closed it by accident? Show QR brings it back.
4. On your phone, open WhatsApp and go to Settings (iPhone) or the ⋮ menu (Android), then Linked devices → Link a device. Scan the code.

A few seconds later the session shows Connected.

Copy the session ID

Your code addresses the session by its ID, not its name. Click View on the session, and Session Details shows the full Session ID: 36 characters, like 3f2a9c1e-8b4d-4e7a-9c3b-1d2e5f6a7b8c. Copy all of it.

Can’t scan the code?

Switch to the Link with Phone Number tab and enter the number with its country code, digits only (919876543210). Then on the phone, go to Linked devices → Link a device → Link with phone number instead, and type the 8-character code the dashboard shows you.

Create a file called send_message.py in the folder that holds OpenWA (next to it, not inside it) and paste this in:

import jsonimport urllib.errorimport urllib.request API_URL = "http://localhost:2785/api"API_KEY = open("OpenWA/data/.api-key").read().strip() SESSION_ID = "paste-your-session-id-here"PHONE = "91XXXXXXXXXX"  # country code + number, digits onlyTEXT = "Hello from my app 👋" request = urllib.request.Request(    f"{API_URL}/sessions/{SESSION_ID}/messages/send-text",    data=json.dumps({"chatId": f"{PHONE}@c.us", "text": TEXT}).encode(),    headers={"Content-Type": "application/json", "X-API-Key": API_KEY},) try:    with urllib.request.urlopen(request) as response:        print("Sent:", json.load(response))except urllib.error.HTTPError as error:    print("Failed:", error.code, error.read().decode())

Then change two lines:

• SESSION_ID: the full ID you copied in step 3.
• PHONE: who you’re messaging. Country code first, then the number, digits only. No +, no spaces, no leading zero.

Save the file and run it from that same folder:

python3 send_message.py

On Windows, the command is python send_message.py. OpenWA shows “typing…” in the chat for a second or two before it sends, so the message looks less automated. Then the script prints something like this:

Sent: {'messageId': 'true_919876543210@c.us_3EB0A1B2C3D4E5F6', 'timestamp': 1791190000}

And the message lands on the other phone. That’s the whole trick: a URL, a key, a chat ID and some text.

What the script does

• Reads your API key straight from OpenWA/data/.api-key, so the key never sits in your code.
• Sends a POST request to your session’s send-text endpoint, with the key in the X-API-Key header.
• Turns the phone number into a WhatsApp chat ID by adding @c.us. Group chats have IDs ending in @g.us.
• Prints OpenWA’s reply: the message ID if it worked, the error if it didn’t.

From your backend

Anything that can make an HTTP request can now send WhatsApp messages. In Node.js, a reusable helper looks like this:

export async function sendWhatsApp(phone, text) {  const url = `${process.env.OPENWA_URL}/sessions/${process.env.OPENWA_SESSION_ID}/messages/send-text`;  const res = await fetch(url, {    method: "POST",    headers: {      "Content-Type": "application/json",      "X-API-Key": process.env.OPENWA_API_KEY,    },    body: JSON.stringify({ chatId: `${phone}@c.us`, text }),  });  if (!res.ok) throw new Error(`OpenWA ${res.status}: ${await res.text()}`);  return res.json();} // After an order is placedawait sendWhatsApp(order.phone, `Order #${order.id} is confirmed.`);

Keep OPENWA_URL (http://localhost:2785/api for now), the session ID and the key in environment variables, never in the code. Here’s why.

And give your app a key of its own. In the dashboard, open API Keys and create an operator key limited to your session. It can send messages but can’t manage keys or settings, and if it ever leaks, you revoke that one key.

Reply to incoming messages

Sending is half a bot. To react when someone writes to you, add a webhook: OpenWA will POST every incoming message to a URL in your app.

curl -X POST http://localhost:2785/api/sessions/YOUR_SESSION_ID/webhooks \  -H "Content-Type: application/json" \  -H "X-API-Key: YOUR_API_KEY" \  -d '{"url": "https://your-app.com/webhooks/whatsapp", "events": ["message.received"], "secret": "a-long-random-string"}'

You can also add it from the Webhooks page in the dashboard. Your endpoint reads the message, decides what to say and answers with the same send-text call. The secret lets you check each delivery’s HMAC signature, so nobody else can feed your bot fake messages.

Hand it to an AI agent

Two ways in. Build it yourself: wrap sendWhatsApp as a tool your agent can call, and feed it the messages your webhook receives. Or use the one that ships with OpenWA: a built-in MCP server, so Claude Code, Cursor and other MCP clients can use WhatsApp directly.

To switch it on, add these two lines to a .env file in the OpenWA folder (create the file if it isn’t there), then stop OpenWA with Ctrl+C and run npm run dev again:

MCP_ENABLED=trueMCP_READONLY=false

MCP_READONLY=false is what lets the agent send. Leave it out and the agent can only read. Then point your client at OpenWA. For Claude Code, that’s a .mcp.json in your project:

{  "mcpServers": {    "openwa": {      "type": "http",      "url": "http://localhost:2785/mcp",      "headers": { "Authorization": "Bearer YOUR_AGENT_KEY" }    }  }}

Wati, Interakt and the other paid tools are built on Meta’s official WhatsApp Business Platform. OpenWA isn’t. It works the way WhatsApp Web does, which is why it’s free and needs nobody’s approval. It’s also why WhatsApp can restrict a number that starts acting like a bot, and no setting in OpenWA can rule that out.

OpenWA’s README lists the habits that keep a number safe. In short:

• Use a dedicated number. Never your main personal or business one.
• Warm up a new number. For the first few days, use it like a person would: chat with saved contacts, join a group or two. Then automate.
• Message people who expect it. Order updates, alerts, replies to people who wrote first. Not cold messages to lists of strangers.
• Go slow. A few messages a minute is sustainable. Thousands an hour is how numbers get banned.
• Keep a fallback. Logins, and anything that makes you money, should also work over SMS or email.

OpenWA or the official API?

A sensible path: prove the idea on OpenWA, then move to the official API once customers rely on it. Keep every send behind one function, like sendWhatsApp above, and that move means rewriting one function instead of hunting through your whole app.

Keeping it running

On your laptop, OpenWA sends only while the laptop is awake and npm run dev is running. For something that’s always on, run it on a server with Docker (docker compose up -d; the README’s production section has the details), and keep the API private: only your backend should be able to reach port 2785.

Open Message Tester in the dashboard, pick your session and send a message from there. If that fails too, the problem is the session, not your script. If it works, find what you’re seeing below.