Connect OpenClaw to WhatsApp

📘 Channel guide: WhatsApp gives your OpenClaw agent huge reach-billions of users. New to OpenClaw? Start with the Quick Start Guide and installation, then return here to add WhatsApp.

Overview

OpenClaw can connect to WhatsApp so you (and users you allow) can chat with your self-hosted AI agent directly in WhatsApp-private chats or groups. Depending on your OpenClaw setup, connection is typically done via QR code pairing (multi-device / “companion” mode) or the WhatsApp Business API (Cloud API) for official business accounts. Either way, your agent gets the same unified memory and skills across all channels, including Telegram and Discord.

This guide covers:

  • Prerequisites: WhatsApp account, OpenClaw installed, and (for Business API) Meta Business verification
  • Connection methods: QR code pairing for personal/multi-device vs WhatsApp Business Cloud API
  • Storing credentials securely (environment variables, secrets)
  • Configuring the WhatsApp channel in OpenClaw
  • Verification and common WhatsApp-specific issues (QR expiry, connection drops, policy limits)
  • Best practices and where to get help

Prerequisites

  • OpenClaw installed and running - Gateway and CLI working. See the Quick Start Guide or installation hub for your platform (macOS, Windows, Linux, Docker).
  • WhatsApp account - A phone number and the WhatsApp app (or WhatsApp Web) for QR-based pairing; for Business API, a Meta Business account and (often) verified business.
  • Basic terminal/CLI - You will run openclaw config edit and optionally openclaw status or use the Web Control UI.

Connection Methods: QR Pairing vs Business API

OpenClaw’s WhatsApp channel can work in two main ways:

  • QR code / multi-device pairing: You scan a QR code (shown in OpenClaw’s Web UI or CLI) with your WhatsApp app to link your number as a “companion” device. No Meta Business account required. Best for personal use, testing, and small teams. The session is tied to your phone number; keep the device/session data secure.
  • WhatsApp Business Cloud API: You use Meta’s official API with a Business account, phone number(s), and (often) business verification. Suited for official business messaging, higher volume, and compliance. Requires a Meta Developer account and app, and may involve approval and fees. See the WhatsApp Cloud API documentation for Meta’s requirements.

Check the official OpenClaw WhatsApp channel docs for your version: they will state which method(s) are supported (e.g. QR-only, API-only, or both) and the exact config schema.

Step 1: Prepare Credentials and Store Them Securely

Depending on the method you use:

  • QR pairing: No long-lived token to store upfront; you will pair in the next step. Ensure the machine running OpenClaw can display or serve the QR code (e.g. Web UI at http://127.0.0.1:18789/ or similar). Session data will be stored locally; protect that directory and follow security best practices.
  • Business API: You will get an access token (and optionally phone number ID, etc.) from the Meta Developer Portal. Store these in environment variables (e.g. WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID) and reference them in the config. Never commit tokens to version control.

Step 2: Add the WhatsApp Channel in OpenClaw

Add the WhatsApp channel to your OpenClaw configuration. Exact schema may vary by OpenClaw version; refer to the official WhatsApp channel documentation for the current structure.

  1. Open your config (e.g. openclaw config edit or edit the config file directly).
  2. Add a channel entry for WhatsApp. Typically you will set:
    • Channel type (e.g. whatsapp)
    • For QR pairing: Often no token; the Web UI or CLI will show a QR code to scan when the gateway starts.
    • For Business API: Access token (prefer env var, e.g. ${WHATSAPP_ACCESS_TOKEN}), and any required IDs (e.g. phone number ID, business account ID) as per the docs.
  3. Save the config and restart the gateway (or let it reload if it supports hot reload).

Example (illustrative; check docs for your version):

# In your OpenClaw config, under channels (or equivalent):
# whatsapp:
#   # For QR pairing, session may be auto-created when you scan.
#   # For Cloud API:
#   accessToken: ${WHATSAPP_ACCESS_TOKEN}
#   phoneNumberId: ${WHATSAPP_PHONE_NUMBER_ID}

For more options (webhook URL, allowed numbers, etc.), see the advanced configuration guide and the official WhatsApp channel docs.

Step 3: Pair (QR) or Verify (API)

  1. QR pairing: Start the gateway and open the Web Control UI (or check CLI output). You should see a WhatsApp QR code. Open WhatsApp on your phone → Linked Devices → Link a Device, and scan the code. After a short sync, OpenClaw’s WhatsApp channel will be connected. Your phone does not need to stay online forever, but the first link and occasional re-link may require the phone.
  2. Business API: Ensure your Meta app is in production or development with WhatsApp enabled, webhook configured if required, and the token/IDs in the config. Use openclaw status to confirm the WhatsApp channel is connected. Send a test message to your business number from a WhatsApp client to verify the agent receives and replies.

Step 4: Verify the Connection

  1. Run openclaw status (or your CLI’s status command) and confirm the WhatsApp channel is listed and connected.
  2. From another WhatsApp account (or the linked number for QR), send a message to the OpenClaw-linked number or business number. Your OpenClaw agent should receive it and respond according to your agent and model setup.
  3. If you use groups, ensure the agent is added to the group and has permission to read and send messages; then send a message and confirm the agent replies.

If the agent does not respond, see Common Issues below and the troubleshooting hub.

Common WhatsApp Issues

Issue Solution
QR code expires or does not appear QR codes typically expire in 60–90 seconds. Refresh the Web UI or restart the gateway to get a new code. Ensure the Web UI is reachable (e.g. http://127.0.0.1:18789/) and no firewall is blocking it.
Connection drops after pairing (QR) Multi-device sessions can log out if the primary phone is offline for a long time or if you log out from “Linked Devices.” Re-scan the QR to re-pair. Keep session data (config/session path) backed up and secure; losing it may require pairing again.
Authentication / 401 (Business API) Verify the access token is correct and not expired. Regenerate the token in the Meta Developer Portal if needed. Ensure no extra spaces or quotes in config or environment variables. Never commit the token to git.
Messages not received or not sent Check that the Gateway is running and the WhatsApp channel is enabled in openclaw status. For Business API, confirm webhook URL is correct and subscribed to the right events. Check OpenClaw logs (openclaw logs) for errors or rate limits.
Number banned or policy warning WhatsApp enforces policies on automation and business use. Avoid spam, respect opt-in and template rules for Business API, and do not use personal QR pairing for large-scale broadcast. If your number is restricted, check Meta’s status and appeal process; for QR, use a different number if necessary.
Rate limits or slow replies WhatsApp applies rate limits. For heavy use, consider official Business API with higher limits. Ensure your OpenClaw instance has enough capacity (model, network). Check logs for throttling or timeout errors.

For more fixes (gateway, config, other channels), see the full troubleshooting hub and channel issues.

Best Practices

  • Keep credentials and session data secret. Use environment variables for API tokens; restrict file permissions on session/store directories. Follow security best practices and never expose the Gateway publicly without proper hardening.
  • Test in a private chat first. Verify the agent responds in a 1:1 chat before adding to groups or sharing the number with many users.
  • Respect WhatsApp policies. Do not spam; for Business API, use approved templates and opt-in flows where required. Automation for personal or internal use with QR is generally acceptable; commercial broadcast must follow Meta’s rules.
  • Stay updated. Keep OpenClaw and the WhatsApp adapter up to date for compatibility with WhatsApp/multi-device and API changes.
  • Monitor logs. Use openclaw logs (or your log path) to catch connection and permission errors early.

Next Steps

Related Resources