OpenClaw WhatsApp Integration Guide

WhatsApp is where most of the world communicates. With over 2 billion users, it's likely your primary messaging app — and that makes it an incredibly powerful channel for your OpenClaw agent. Having your AI assistant available in the same app where you chat with family, friends, and colleagues means it's always just a message away.

WhatsApp integration is slightly more complex than Telegram because there's no official bot API for personal accounts. But the result is worth it — your agent responds from your actual WhatsApp number, making the experience seamless.

How WhatsApp Integration Works

Unlike Telegram (which has a dedicated Bot API), WhatsApp integration works through a web bridge — essentially the same technology that powers WhatsApp Web and WhatsApp Desktop. OpenClaw connects to your WhatsApp account via QR code, then can read incoming messages and send responses.

Important to understand: Messages come from your WhatsApp number. Your contacts see responses as coming from you, not from a separate bot account. This has implications for transparency and how you configure the agent's behavior.

Step 1: Prerequisites

• OpenClaw installed and gateway running
• A WhatsApp account with an active phone number
• Your phone with WhatsApp installed (needed for initial QR code scan)

Step 2: Add the WhatsApp Channel

After scanning the QR code, the connection establishes within seconds. Your gateway is now linked to your WhatsApp account.

Step 3: Configure Who the Agent Responds To

This is critical. Unlike Telegram (where people message a bot and know they're talking to AI), WhatsApp messages come from your personal number. You need to decide:

Option A: Respond Only to Your Own Messages

The safest starting configuration. The agent only processes messages you send to yourself (using WhatsApp's "Message Yourself" feature) or messages from specific contacts you whitelist.

Option B: Respond to Specific Contacts

Whitelist specific phone numbers or contacts. The agent responds to messages from these contacts and ignores everyone else.

Option C: Respond to All Messages

The agent processes all incoming messages. This requires careful SOUL.md configuration to avoid awkward situations.

I recommend starting with Option A or B. Expand to Option C only after you're confident in your agent's behavior and your contacts are aware you're using AI assistance.

Step 4: WhatsApp-Specific SOUL.md Rules

Add WhatsApp-specific behavior to your SOUL.md:

Media Handling

WhatsApp is a media-rich platform. Your OpenClaw agent can handle:

Receiving

• Photos and videos — Analyzed with vision models if configured
• Voice messages — Transcribed to text for processing
• Documents — PDFs, spreadsheets, and other files can be read
• Location shares — Processed as geographic context
• Contacts — Contact cards can be read and stored

Sending

• Text messages — With WhatsApp formatting (bold, italic, monospace)
• Images — Generated images or screenshots
• Voice notes — Via TTS for audio responses
• Documents — Files from the workspace

Group Chat Behavior

WhatsApp groups require the most careful configuration. Your agent sees all messages in groups your account belongs to. Without rules, it might respond to everything — which is disastrous in a family group chat.

Recommended group chat rules:

• Mention-only mode: Agent responds only when your name is mentioned or it's directly addressed
• Silent observation: Agent reads group messages for context (useful for memory) but never responds unless you explicitly instruct it
• Selective groups: Whitelist specific groups where the agent can participate; mute all others

Connection Stability

The WhatsApp web bridge connection can occasionally disconnect. Common causes and solutions:

Phone Goes Offline

WhatsApp's multi-device support has improved this significantly, but extended phone downtime can still cause disconnections. Solution: Keep your phone connected to WiFi and powered.

WhatsApp Updates

Major WhatsApp updates occasionally break the web bridge temporarily. Solution: Keep OpenClaw updated, as the community typically patches bridge compatibility within days.

Session Expiry

WhatsApp linked device sessions can expire after 14 days of phone inactivity. Solution: Ensure your phone opens WhatsApp at least once every two weeks.

WhatsApp vs Telegram: Which Channel First?

Factor	WhatsApp	Telegram
Setup Difficulty	Medium (QR bridge)	Easy (Bot API)
Identity	Your phone number	Separate bot account
Connection Stability	Occasional re-linking	Very stable
Rich Features	End-to-end encryption	Inline buttons, reactions
User Base	2B+ users globally	900M+ users

Recommendation: Start with Telegram for ease of setup and clear bot identity. Add WhatsApp once you're comfortable with your agent's behavior and want it in your primary messaging app.

Privacy Considerations

WhatsApp messages are end-to-end encrypted between devices. However, when your OpenClaw agent processes messages, they're decrypted on your machine and then sent to the AI model provider's API for processing. This means:

• Messages are encrypted in transit between WhatsApp users
• Messages are decrypted on your gateway machine
• Message content is sent to OpenAI/Anthropic/etc. for AI processing
• Responses are encrypted back through WhatsApp

For maximum privacy, use local models via Ollama — this keeps everything on your hardware. For details on security configuration, see our Security Guide.

Practical WhatsApp Use Cases

• Quick queries on the go: Ask your agent questions while walking, driving (voice), or commuting
• Morning briefing delivery: Receive your daily briefing in WhatsApp, read it over coffee
• Photo analysis: Snap a photo and ask your agent to analyze it (receipts, documents, products)
• Voice interaction: Send voice notes, get voice responses — hands-free AI assistance
• Family coordination: Agent helps manage schedules and reminders through family groups

Frequently Asked Questions