open-wa logoopen-wa

Bot in Python

Answer WhatsApp messages from a Python app that receives a webhook and replies through the Easy API.

Build a WhatsApp bot in Python

This guide shows how to build a WhatsApp bot in Python. open-wa runs the WhatsApp session in Node.js. Your Python application receives messages through a webhook and replies through the HTTP API.

WhatsApp -> open-wa Easy API -> webhook -> Python app -> POST /api/messages/sendText

Before you start

  • Install Node.js 22.21.1 or newer for the open-wa process.
  • Install Python 3.10 or later.
  • Keep a phone with WhatsApp near you to link the account.

1. Create the Python receiver

Install Flask and requests:

pip install flask requests

Create bot.py. The receiver checks the shared secret, reads the message, and replies through the Easy API.

import hmac
import os

import requests
from flask import Flask, abort, request

API_URL = "http://127.0.0.1:8080"
API_KEY = os.environ["WA_API_KEY"]
WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]

app = Flask(__name__)


def send_text(chat_id: str, text: str) -> None:
    response = requests.post(
        f"{API_URL}/api/messages/sendText",
        headers={"X-API-Key": API_KEY},
        json={"to": chat_id, "content": text},
        timeout=30,
    )
    response.raise_for_status()


@app.post("/webhooks/open-wa")
def webhook():
    secret = request.headers.get("X-Webhook-Secret", "")
    if not hmac.compare_digest(secret, WEBHOOK_SECRET):
        abort(401)

    envelope = request.get_json(silent=True)
    if not envelope:
        abort(400)

    if envelope.get("event") == "message.received":
        message = envelope["payload"]["message"]
        body = (message.get("body") or "").strip().lower()
        if body == "!help":
            send_text(message["from"], "Commands: !help, !hours")
        elif body == "!hours":
            send_text(message["from"], "We are open Monday to Friday, 09:00 to 17:00.")

    return "", 204


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)

Start the receiver before you start open-wa:

export WA_API_KEY='use-a-long-random-value'
export WEBHOOK_SECRET='use-a-different-long-random-value'
python bot.py

2. Configure open-wa

In a new directory, install the webhook integration:

npm install @open-wa/wa-automate @open-wa/integration-webhook

Create wa.config.mjs in the same directory:

const webhookSecret = process.env.WEBHOOK_SECRET?.trim();
if (!webhookSecret) throw new Error('WEBHOOK_SECRET is required');

export default {
  sessionId: 'python-bot',
  host: '127.0.0.1',
  port: 8080,
  plugins: ['@open-wa/integration-webhook'],
  pluginConfig: {
    webhook: {
      url: 'http://127.0.0.1:5000/webhooks/open-wa',
      events: ['message.received'],
      headers: { 'X-Webhook-Secret': webhookSecret },
    },
  },
};

3. Start open-wa

Set the same two values in this terminal, then start the Easy API from that directory. It finds wa.config.mjs on its own and reads the API key from WA_API_KEY:

export WA_API_KEY='use-a-long-random-value'
export WEBHOOK_SECRET='use-a-different-long-random-value'
npx @open-wa/wa-automate

Scan the QR code with WhatsApp on your phone. Then send !help to the linked account from another phone. The bot replies in the same chat.

Respond quickly

open-wa waits for the webhook response. A slow response uses a delivery slot and can cause a retry after a timeout. Return 204 quickly. For slow work, put the message in a queue and send the reply from a worker.

A retry can send the same event again. To prevent a duplicate reply, store payload.message.id and ignore an ID that you already processed.

Send messages without a webhook

To send a notification from a Python script, call the HTTP API directly. You do not need the webhook for this task.

import requests

requests.post(
    "http://127.0.0.1:8080/api/messages/sendText",
    headers={"X-API-Key": "use-a-long-random-value"},
    json={"to": "447123456789@c.us", "content": "Your order has shipped."},
    timeout=30,
).raise_for_status()

Read send a WhatsApp message with the API for the chat ID format and license rules.

Was this helpful?

Your answer includes the page path and docs version.

On this page