WhatsApp Bot

Connect your AI agent to WhatsApp — Cloud API or Web mode

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).

from praisonaiagents import Agent
from praisonai.bots import WhatsAppBot

agent = Agent(name="assistant", instructions="Be helpful on WhatsApp.", llm="gpt-4o-mini")
bot = WhatsAppBot(mode="web", agent=agent)

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

The user messages on WhatsApp; the bot forwards the chat to the agent and replies in the thread.

Quick Start

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

Inbound Media → Vision

Photos and documents sent by users are downloaded via the WhatsApp Graph API, validated, and forwarded to your agent’s vision capability — no placeholder text, no extra code.

sequenceDiagram
    participant U as 👤 User
    participant WA as 📲 WhatsApp
    participant Bot as 🤖 WhatsApp Bot
    participant M as 🛡️ Media Validator
    participant A as 🧠 Agent Vision

    U->>WA: Send photo + caption
    WA->>Bot: Webhook (image id + caption)
    Bot->>WA: Download media via Graph API
    WA-->>Bot: Raw bytes
    Bot->>M: cache_inbound_media()
    Note over M: Size cap check (≤ 20 MiB)<br/>Magic-byte content-type check<br/>SSRF-safe URL fetch
    M-->>Bot: Validated local path
    Bot->>A: chat(prompt=caption, attachments=[path])
    A-->>Bot: Vision response
    Bot-->>U: 📨 Reply with image description

    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef platform fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef security fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff

1. Vision agent — works out of the box

   Any vision-capable model receives photos automatically. No configuration needed.

   from praisonaiagents import Agent
   from praisonai.bots import WhatsAppBot
   
   agent = Agent(
       name="vision-assistant",
       instructions="Describe and answer questions about images.",
       llm="gpt-4o",
   )
   
   bot = WhatsAppBot(agent=agent)
   
   import asyncio
   asyncio.run(bot.start())

   Send a photo to your WhatsApp business number. The agent sees the image and replies.

2. Limit or disable inbound media

   Control media size or disable it entirely with max_inbound_media_bytes.

   from praisonaiagents import Agent
   from praisonai.bots import WhatsAppBot
   from praisonaiagents import BotConfig
   
   agent = Agent(name="assistant", instructions="Be helpful.", llm="gpt-4o")
   
   bot = WhatsAppBot(
       agent=agent,
       config=BotConfig(
           max_inbound_media_bytes=5 * 1024 * 1024,  # 5 MiB cap
           # max_inbound_media_bytes=0  # set 0 to disable entirely
       ),
   )
   
   import asyncio
   asyncio.run(bot.start())

How the security pipeline works

Configuration

Interactive Messages

WhatsApp bots render MessagePresentation natively — approval buttons, quick replies, and select menus become tappable Cloud API interactive messages, with no code change to existing agents.

import asyncio
from praisonaiagents.bots import MessagePresentation
from praisonai_bot.bots import WhatsAppBot

bot = WhatsAppBot(
    token="YOUR_TOKEN",
    phone_number_id="YOUR_PHONE_ID",
)

presentation = MessagePresentation.approval(
    prompt="Allow file delete?",
    approval_id="appr-1",
)

async def main():
    # ≤3 non-URL buttons → native reply-button message
    await bot.render_presentation("15551234567", presentation)

asyncio.run(main())

import asyncio
from praisonaiagents.bots import MessagePresentation, PresentationBlock, SelectOption
from praisonai_bot.bots import WhatsAppBot

bot = WhatsAppBot(
    token="YOUR_TOKEN",
    phone_number_id="YOUR_PHONE_ID",
)

presentation = MessagePresentation(blocks=[
    PresentationBlock.make_text("Pick an environment:"),
    PresentationBlock.make_select(
        options=[
            SelectOption(label="Staging", value="staging"),
            SelectOption(label="Production", value="prod"),
        ],
        placeholder="Choose",
        action_id="env",
    ),
])

async def main():
    # select block → native list message (up to 10 rows)
    await bot.render_presentation("15551234567", presentation)

asyncio.run(main())

How WhatsApp adapts

See Bot Presentations for the portable model shared across Telegram, Slack, Discord, and WhatsApp.

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.

Identity canonicalization runs first, so every later check — self-chat, outgoing guard, and allowlist — sees one stable phone-form identity regardless of whether the message arrived as a <lid>@lid or <phone>@s.whatsapp.net JID. See Identity: LID vs phone JID.

Four Layers of Protection

Identity: LID vs phone JID

In Web mode, WhatsApp may address the same person with two interchangeable JIDs — the privacy LID (<lid>@lid) and the phone JID (<phone>@s.whatsapp.net) — and the web bridge can surface either form for the same person across messages.

The adapter reconciles both to the phone form before any allowlist, session, memory, or pairing key is derived. It learns the mapping from whatsmeow’s SenderAlt alternate-JID field, so:

• Allowlists match either form. A phone-number entry authorises the same person whether they arrive as <lid>@lid or <phone>@s.whatsapp.net.
• One session and memory bucket. LID-form and phone-form turns from the same person resolve to a single canonical id — no split history.
• Stable pairing. Pairing state carries across both forms, so an already-paired user is never asked to re-pair.
• Self-chat stays self-chat. Same-session self-chat detection compares the canonicalized chat form, so an LID-addressed self-chat is never mistaken for an outgoing message and dropped.

No configuration is required. An unknown address is returned unchanged (fail-open) — behaviour is never worse than passing the raw JID through.

Expand Who Can Message the Bot

praisonai bot whatsapp --mode web

# 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

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

Register custom commands:

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

CLI Options

praisonai bot whatsapp --mode web [OPTIONS]

Architecture

Key Components

Long Agent Turns

A long agent turn on WhatsApp — deep research, big refactor, a slow model — stays BUSY for as long as it is making any progress, and is never restarted mid-stream.

The gateway watches each channel’s health and only restarts a channel when it is genuinely wedged. Progress comes from inbound transport activity (someone messaged the bot) and in-run progress (the agent emitted a streamed token, called a tool, or fired an emitter event). As long as either signal advanced within stuck_after (default 900s), the channel stays BUSY and will not be killed. Only when no signal arrives for stuck_after seconds does the channel escalate to STUCK (recoverable, will be restarted).

sequenceDiagram
    participant User as WhatsApp User
    participant WA as WhatsApp Adapter
    participant Agent
    participant Health as Channel Health

    User->>WA: Run a deep research task
    WA->>Agent: start run (active_runs=1)
    Agent-->>WA: streamed token
    WA->>Health: note_run_progress()
    Agent-->>WA: tool call
    WA->>Health: note_run_progress()
    Health-->>WA: BUSY (within stuck_after)
    Agent-->>WA: final answer
    WA-->>User: reply

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff

    class Agent agent
    class User,WA tool
    class Health decision

Troubleshooting

pip install --upgrade praisonai

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

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

WARNING Error sending close to websocket

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

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

rm -rf ~/.praisonai/whatsapp/

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

Best Practices

Standalone scheduled delivery (no gateway)

You do not need a running WhatsApp Bot process to deliver a scheduled brief to WhatsApp. From OS cron / CI / a scale-to-zero deployment, praisonai schedule tick will POST directly to the WhatsApp Cloud API using the same env the live bot reads (WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, and either an explicit deliver: whatsapp:<recipient> target or WHATSAPP_HOME_CHANNEL). Sends are retried up to 4 times with exponential backoff on transient failures. See Out-of-process delivery.

Related