WhatsApp Bot

Connect your AI agent to WhatsApp with a single command. Choose between the official Cloud API (production) or Web mode (scan a QR code, no tokens needed).

Quick Start

Web Mode (Easiest)
Cloud API (Production)
Python SDK

No tokens, no developer account — just scan a QR code.

Install

pip install 'praisonai[bot-whatsapp-web]'

Start

praisonai bot whatsapp --mode web

A QR code appears in your terminal. Open WhatsApp → Linked Devices → scan it.

Chat

Open your own contact (message yourself) and send a message. The bot replies.

Experimental — Web mode uses a reverse-engineered protocol. Your number may be banned by WhatsApp. Use Cloud API for production.

Uses the official Meta WhatsApp Business API.

Get Credentials

Go to Meta for Developers
Create an app → add the WhatsApp product
Copy your Phone Number ID and Access Token

Set Environment Variables

export WHATSAPP_ACCESS_TOKEN="EAAx..."
export WHATSAPP_PHONE_NUMBER_ID="123456789"
export WHATSAPP_VERIFY_TOKEN="my-secret"

Start

praisonai bot whatsapp

This starts a webhook server on port 8080. Point your Meta webhook URL to https://your-domain.com/webhook.

from praisonaiagents import Agent
from praisonai.bots import WhatsAppBot

agent = Agent(
    name="assistant",
    instructions="You are a helpful AI assistant",
    llm="gpt-4o-mini"
)

# Web mode — no tokens needed
bot = WhatsAppBot(mode="web", agent=agent)

import asyncio
asyncio.run(bot.start())

How It Works

Cloud API vs Web Mode

Feature	Cloud API	Web Mode
Setup	Meta developer account + tokens	QR code scan
Stability	Official, stable	Reverse-engineered, may break
Webhooks	Required (public HTTPS)	Not needed
Groups	DMs only	DMs + groups
Risk	None	Account may be banned
Best for	Production	Development, personal use

Message Filtering

By default, the bot responds only to self-chat — when you message your own number. This prevents it from replying to every conversation.

Four Layers of Protection

Stale Message Guard

Messages older than when the bot connected are dropped. Prevents replaying old conversations on reconnect.

Self-Chat Check

Only messages where sender = chat JID pass.

Outgoing Guard

Your messages sent to other people’s chats are always blocked — even if they’re in the allowlist.

Allowlists

Optionally allow specific phone numbers or groups.

Expand Who Can Message the Bot

Self-Only (Default)
Specific Numbers
Specific Groups
Everyone

praisonai bot whatsapp --mode web

Only responds when you message your own number.

# Comma-separated
praisonai bot whatsapp --mode web --respond-to 1234567890,9876543210

# Or repeated flags
praisonai bot whatsapp --mode web --respond-to 1234567890 --respond-to 9876543210

# Comma-separated
praisonai bot whatsapp --mode web --respond-to-groups 120363123456@g.us,999888777@g.us

# Or repeated flags
praisonai bot whatsapp --mode web --respond-to-groups 120363123456@g.us --respond-to-groups 999888777@g.us

praisonai bot whatsapp --mode web --respond-to-all

Filtering Matrix

Scenario	Default	`--respond-to 123`	`--respond-to-groups g@g.us`	`--respond-to-all`
Self-chat (your own number)	✅	✅	✅	✅
Your msg in someone else’s chat	❌	❌	❌	✅
DM from 123	❌	✅	❌	✅
DM from 999	❌	❌	❌	✅
Group g@g.us	❌	❌	✅	✅
Other group	❌	❌	❌	✅
Old/offline messages	❌	❌	❌	❌

Phone numbers are normalized automatically — +1-234-567-890 and 1234567890 match the same number.

Python SDK Filtering

from praisonai.bots import WhatsAppBot

bot = WhatsAppBot(
    mode="web",
    agent=agent,
    allowed_numbers=["1234567890", "9876543210"],
    allowed_groups=["120363123456@g.us"],
    respond_to_all=False,  # default
)

YAML Config

platform: whatsapp
mode: web

respond_to:
  - "1234567890"
respond_to_groups:
  - "120363123456@g.us"
respond_to_all: false

agent:
  name: "My Assistant"
  instructions: "You are a helpful AI assistant."
  llm: "gpt-4o-mini"

praisonai bot start --config bot.yaml

Built-in Commands

Command	Description
`/help`	Show available commands
`/status`	Bot info, model, uptime
`/new`	Reset conversation session

@bot.on_command("ping")
async def ping(msg):
    return "Pong!"

CLI Options

praisonai bot whatsapp --mode web [OPTIONS]

Flag	Description	Example
`--mode`	`cloud` (default) or `web`	`--mode web`
`--respond-to`	Allowed phone numbers (comma-separated or repeated)	`--respond-to 123,456` or `--respond-to 123 --respond-to 456`
`--respond-to-groups`	Allowed group JIDs (comma-separated or repeated)	`--respond-to-groups grp@g.us`
`--respond-to-all`	Respond to everyone	`--respond-to-all`
`--creds-dir`	Credentials directory	`--creds-dir ~/.myapp/wa`
`--agent`	Agent YAML config	`--agent agents.yaml`
`--memory`	Enable conversation memory	`--memory`
`--web`	Enable web search tool	`--web`
`--thinking`	Extended thinking mode	`--thinking high`
`--auto-approve`	Auto-approve tool calls	`--auto-approve`

Architecture

Key Components

Component	Role
WhatsAppBot	Main bot class — handles lifecycle, filtering, routing
WhatsAppWebAdapter	Bridges neonize (Go) events to Python asyncio
Session Manager	Per-user conversation sessions with expiry
Message Filter	Stale guard → self-chat check → allowlist check
AI Agent	Your configured agent processes the message and responds

Troubleshooting

Bot responds to old messages on startup

Fixed in latest version. The stale-message guard drops any message older than when the bot connected. If you still see this, update to the latest version:

pip install --upgrade praisonai

Bot responds to all messages, not just self-chat

Fixed in latest version. The default filter now checks that both the sender AND chat JID match (true self-chat), not just IsFromMe. Update your installation.

Decryption warnings in the logs

WARNING Ignoring message ... failed to decrypt prekey message
WARNING Ignoring message ... failed to decrypt group message

These are normal and harmless. They come from the WhatsApp protocol layer (whatsmeow) when old session keys can’t decrypt certain messages. The bot automatically suppresses most of these. They don’t affect functionality.

SessionCipher error: old counter

[ERROR] SessionCipher.go:310 ▶ Unable to get or create message keys

This is an upstream protocol error from the Signal encryption layer. It means a message had expired keys. This is not a bug in PraisonAI — it’s a normal part of the WhatsApp protocol. The message is simply skipped.

WebSocket close error on shutdown

WARNING Error sending close to websocket

This appears when Ctrl+C is pressed. It’s harmless — the bot is disconnecting from WhatsApp servers. The latest version suppresses this warning.

shell_tools error: /home/user not found

ERROR Error executing command: No such file or directory: '/home/user'

This happens when the AI agent tries to run a command in /home/user (a Linux path) on macOS. Fixed in latest version — the tool now automatically falls back to your home directory.

Threading error on Ctrl+C

Exception ignored in: <module 'threading' ...>
KeyboardInterrupt

Fixed in latest version. The bot now properly shuts down background threads on exit. Update your installation.

QR code not showing

Use a modern terminal (iTerm2, Windows Terminal)
Ensure segno is installed: pip install 'praisonai[bot-whatsapp-web]'
If a saved session exists, no QR is needed. Delete to re-link:

rm -rf ~/.praisonai/whatsapp/

Session expired

WhatsApp Web sessions expire if your phone is offline for 14+ days. Delete and re-scan:

rm -rf ~/.praisonai/whatsapp/
praisonai bot whatsapp --mode web

Messaging Bots

All supported platforms: Telegram, Discord, Slack, WhatsApp

WhatsApp MCP

Send WhatsApp messages from agents using MCP tools

Bot Commands

Custom command registration and handling

Approval Protocol

Human-in-the-loop tool approval for bots

Getting Started

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Cloud API vs Web Mode

Message Filtering

Four Layers of Protection

Stale Message Guard

Self-Chat Check

Outgoing Guard

Allowlists

Expand Who Can Message the Bot

Filtering Matrix

Python SDK Filtering

YAML Config

Built-in Commands

CLI Options

Architecture

Key Components

Troubleshooting

Messaging Bots

WhatsApp MCP

Bot Commands

Approval Protocol

Getting Started

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

​Quick Start

​How It Works

​Cloud API vs Web Mode

​Message Filtering

​Four Layers of Protection

Stale Message Guard

Self-Chat Check

Outgoing Guard

Allowlists

​Expand Who Can Message the Bot

​Filtering Matrix

​Python SDK Filtering

​YAML Config

​Built-in Commands

​CLI Options

​Architecture

​Key Components

​Troubleshooting

​Related

Messaging Bots

WhatsApp MCP

Bot Commands

Approval Protocol

Quick Start

How It Works

Cloud API vs Web Mode

Message Filtering

Four Layers of Protection

Expand Who Can Message the Bot

Filtering Matrix

Python SDK Filtering

YAML Config

Built-in Commands

CLI Options

Architecture

Key Components

Troubleshooting

Related