WhatsApp Integration: Full Setup Guide
Connect OpenClaw to WhatsApp so your agent can send and receive messages, images, and documents from any phone or desktop.
What You Will Get
By the end of this guide, your OpenClaw agent will be fully connected to WhatsApp. Anyone who messages your linked WhatsApp number will receive real-time replies from your agent, complete with text, images, and document support.
WhatsApp is the most widely used messaging platform globally, making it the ideal channel if your audience prefers mobile-first communication. Once connected, your agent maintains a persistent session so it stays online across restarts without requiring a new QR scan every time.
You will also learn how to handle media messages, send files back to users, and keep your WhatsApp session healthy over time. This gives you a fully functional WhatsApp-based assistant that works around the clock.
Step-by-Step Setup
Follow these steps to connect your OpenClaw agent to WhatsApp.
Open the Channels Panel
Navigate to your agent dashboard on RunTheAgent and select the Channels tab from the left sidebar. This is where all your communication integrations live. You will see a list of available channel types ready to be configured.
Select WhatsApp
Click the WhatsApp option from the channel list. This opens the WhatsApp configuration panel where you can initiate the pairing process. Make sure you have a phone with WhatsApp installed and ready nearby.
Scan the QR Code
A QR code will appear on screen. Open WhatsApp on your phone, go to Settings, then Linked Devices, and tap Link a Device. Point your phone camera at the QR code displayed in the dashboard. The connection establishes within seconds.
Verify the Connection
Once the QR code is scanned, the dashboard will show a green connected status. Send a test message from another phone to your linked WhatsApp number to confirm the agent responds. Check the logs tab to verify the message was received and processed correctly.
Configure Session Persistence
Enable session persistence in the WhatsApp channel settings. This stores your authentication tokens so the agent reconnects automatically after a restart or deployment. Without this, you would need to re-scan the QR code each time the agent restarts.
Enable Media Support
Toggle on media handling in the channel settings to allow your agent to receive and send images, PDFs, audio messages, and other file types. Configure the maximum file size and allowed media types based on your use case. This ensures your agent can handle rich conversations beyond plain text.
Set Up Message Formatting
WhatsApp supports bold, italic, strikethrough, and monospace formatting. Configure your agent's response template to use WhatsApp-compatible markdown so replies look clean and professional. Test different formatting styles by sending yourself a few messages to see how they render on mobile.
Tips and Best Practices
Keep Your Phone Online
WhatsApp Web connections require the linked phone to have internet access periodically. Keep your primary device connected to Wi-Fi to avoid session drops.
Use a Dedicated Number
Consider using a separate phone number for your agent to keep personal and agent conversations separate. This also prevents accidental interference with your personal chats.
Monitor Session Health
Check the channel status indicator on your dashboard regularly. If the session drops, the system will alert you and you can re-scan quickly from the Channels panel.
Respect Rate Limits
WhatsApp enforces messaging rate limits to prevent spam. Keep your agent's response frequency reasonable and avoid sending bulk unsolicited messages to maintain account health.
Frequently Asked Questions
Related Pages
Ready to get started?
Deploy your own OpenClaw instance in under 60 seconds. No VPS, no Docker, no SSH. Just your personal AI assistant, ready to work.
Starting at $24.50/mo. Everything included. 3-day money-back guarantee.
