Guide

Deploy OpenClaw WhatsApp Integration for Developers: QR Pairing Today

2026-10-06

Deploy OpenClaw WhatsApp Integration for Developers: QR Pairing Today

Yes, OpenClaw connects to WhatsApp, and for most personal or small-team setups the fastest path is WhatsApp Web through Baileys, paired by QR code. High-volume business messaging calls for the official Business API instead. Once the gateway is running, pairing starts with one command: openclaw channels login --channel whatsapp.

***

> TL;DR:

>

> - Using WhatsApp Web via Baileys allows quick setup without Meta approval, but requires regular QR code scanning and session management.

> - The official Business API is better suited for high-volume messaging, verified accounts, and template-based communication, but involves longer setup time.

> - Gateway deployment should be supervised on Node.js, with dedicated credentials for multiple accounts, and process management for reliability.

> - Media size limits are 50 MB inbound, and session recovery often involves re-logging, restarting the gateway, or renewing pairing requests.

> - Scaling for larger volume involves multiple gateway instances with separate auth directories, response model optimization, and avoiding shared session slots.

***

Table of Contents

How OpenClaw, the gateway, and WhatsApp work together

OpenClaw's WhatsApp integration runs through a few distinct layers, and understanding each one tells you where to look when something breaks. A message arrives over the WhatsApp Web socket (via Baileys) or through a webhook (via the Business API), lands at the gateway, which owns the session and routing logic, then gets handed to an agent, which queries a model for a response.

OpenClaw WhatsApp message routing layers

The Baileys path is the reverse-engineered WhatsApp Web client: you scan a QR code, the gateway maintains a persistent socket connection, and no Meta approval or business verification is required. The Business API path is the official, Meta-supported route: it uses webhooks and access tokens instead of a live socket, and it is built for template messaging and verified business accounts at scale.

Credentials and session state live in an auth directory tied to the gateway, and according to OpenClaw's documentation, the WhatsApp channel is production-ready through WhatsApp Web, with no separate Twilio-based channel in the architecture. Multi-account setups each need their own credential directory, which keeps a personal assistant and a business line from colliding.

Deploying the OpenClaw gateway and starting the base instance

Before WhatsApp enters the picture, you need a running gateway. We recommend Node.js as the runtime: OpenClaw's getting-started documentation flags alternative runtimes like Bun as unreliable for the WhatsApp gateway specifically, which is a common and avoidable source of intermittent disconnects.

A typical self-hosted quickstart looks like this:

  • Install Node.js and confirm proxy environment variables are set correctly if your host sits behind a corporate network.
  • Run the onboarding flow (openclaw onboard) and install any required plugins.
  • Start the gateway with openclaw gateway and confirm it is alive with openclaw status.
  • Keep the process supervised (systemd, pm2, or a container restart policy) so a crash does not silently kill your WhatsApp session.

If you would rather skip host provisioning, proxy tuning, and runtime babysitting entirely, a managed quickstart gets a dedicated instance running with one click and backs it with a 99.9% uptime target, which matters once WhatsApp sessions depend on a gateway that never silently drops.

Configuring the agent, model, and session policy before going live

Before WhatsApp traffic starts flowing, set the agent and model configuration that will govern every reply. Pick a primary model and a fallback, since a single-model dependency means an outage on one provider takes your assistant offline entirely. Configure reasonable timeouts and heartbeat intervals so a slow model response does not stall the WhatsApp socket.

Session scope matters more for WhatsApp than for most channels, because DMs and group chats behave differently. Set history limits and reset triggers that fit the conversation type: a support DM might carry long context, while a group thread usually benefits from a shorter, more aggressively trimmed window to avoid the agent replying off stale context.

Security-relevant fields deserve conservative defaults from day one:

  • dmPolicy controls whether direct messages are accepted automatically, require approval, or are blocked.
  • allowFrom restricts which numbers can reach the agent at all, which is the single most effective control against unwanted inbound traffic.
  • groupPolicy governs whether the agent participates in group chats by default or only when explicitly invited.

Start restrictive. It is far easier to loosen allowFrom for a trusted contact later than to clean up after an open assistant number gets flooded by strangers.

Installing the WhatsApp plugin and pairing your account

With the gateway running and agent configured, connecting WhatsApp itself is a short sequence.

  1. Install the WhatsApp channel plugin if it is not already bundled (npm:@openclaw/whatsapp or the equivalent clawhub: package reference).
  2. Run openclaw channels login --channel whatsapp to generate a pairing QR code.
  3. Open WhatsApp on your phone, go to Linked Devices, and scan the code. Each linked device consumes one of four available slots, as OpenClaw's integration guide notes, so clear out stale sessions if you are near the limit.
  4. Confirm the session is active with openclaw channels status.

On headless or remote servers, a terminal-rendered QR can time out before you manage to scan it. OpenClaw's setup guide recommends piping the code to an image file or capturing a screenshot instead of relying on a live terminal render, which avoids most expired-QR failures.

For multi-account setups, point each instance at its own authDir so credentials never mix, and apply per-account overrides for allowFrom and dmPolicy rather than sharing one global policy across a personal and a business number.

Pro Tip: *Pair from a desktop terminal with a large monitor rather than SSH over a laggy connection: QR scan failures are almost always a rendering or timing problem, not a configuration one.*

WhatsApp runtime settings for media, chunking, and groups

WhatsApp has its own message-size and formatting constraints, and OpenClaw exposes a handful of settings to work within them.

  • textChunkLimit defaults to 4,000 characters, per OpenClaw's WhatsApp channel documentation, and chunkMode controls how longer replies get split across multiple messages.
  • mediaMaxMb defaults to 50 MB for inbound media, so large files get rejected before they ever reach the model.
  • sendReadReceipts and ackReaction control whether the agent marks messages as read or reacts to confirm receipt, both small signals that make an automated assistant feel more responsive.

The default inbound media ceiling is 50 MB, which covers most voice notes and images, but will reject longer video clips outright.

Group behavior is governed separately: mentionPatterns and requireMention keep the agent silent until directly addressed, while groupPolicy and groupAllowFrom decide which groups it participates in at all. We recommend a dedicated assistant number paired with a tight allowFrom list rather than exposing your personal WhatsApp number to an automated agent.

Diagnosing and recovering disconnected WhatsApp sessions

WhatsApp sessions fail in a handful of predictable ways, and OpenClaw's CLI gives you a fast path to figure out which one you are looking at.

  • Run openclaw channels status first to confirm the session is actually linked, not just configured.
  • Use openclaw pairing list to check for pending or expired pairing requests, which according to setup documentation time out after an hour and are capped in number.
  • Go deeper with openclaw status --deep and openclaw health --json when the surface-level status looks fine but messages still are not flowing.

The usual culprits are an expired QR code, a duplicate gateway instance fighting over the same session, a runtime incompatibility (Node versus Bun, as noted earlier), or a proxy misconfiguration blocking the socket. Recovery is usually one of: re-login via openclaw channels login, re-attach the correct authDir, approve a stuck pairing request, or simply restart the gateway and watch the logs for the specific error. A structured troubleshooting checklist can save real time versus guessing through each possibility in sequence.

Scaling strategies and performance optimization for OpenClaw WhatsApp integration

A single WhatsApp-linked gateway handles personal or small-team volume comfortably, but scaling introduces new bottlenecks worth planning for early. The WhatsApp Web socket itself is single-session per linked device, so horizontal scaling means running multiple gateway instances, each with its own authDir and its own linked number, rather than trying to fan one session out across workers.

Separate gateway instances for WhatsApp scaling

Model latency is usually the real bottleneck, not WhatsApp itself. Configuring a fast fallback model for simple queries and reserving a heavier model for complex requests keeps response times predictable under load. Session history limits matter here too: a long, untrimmed conversation history means every request ships more tokens to the model, which adds latency and cost without necessarily improving answer quality.

Chunking settings interact with performance in a less obvious way. A high textChunkLimit paired with slow model generation can make responses feel sluggish because WhatsApp is waiting on the full chunk before sending, while splitting into smaller chunks earlier can let the first part of a reply arrive faster.

For teams running several WhatsApp-linked agents at once, isolating each on its own gateway process, rather than one gateway juggling many accounts, keeps a crash or reconnect storm on one line from taking every other line down with it. This is one area where managed, dedicated infrastructure pays off: a host that guarantees uptime and handles reconnect logic removes a whole category of scaling failures that otherwise fall on whoever is watching the logs at 2 a.m.

Real-world use cases for OpenClaw on WhatsApp

The most common deployment we see is a personal assistant reachable from your own number: forwarding a note, asking it to summarize a document, or triggering a workflow, all from the same app you already use daily. Self-chat mode, where your own number sits in allowFrom, is a popular pattern specifically for this kind of command-and-control use, as OpenClaw's documentation notes.

Small businesses use the Baileys path for lightweight customer response: answering frequently asked questions, confirming appointment times, or routing a question to a human when the agent cannot resolve it. Because this path does not require Meta business verification, it is often the fastest way to get an automated WhatsApp presence running for a storefront or local service.

Group-based use cases lean on requireMention and mentionPatterns: a shared family or team group where the agent only responds when explicitly addressed, filtering out the rest of the conversation. This keeps the assistant useful without it becoming noise in an active thread.

Higher-volume businesses, particularly ones sending order confirmations, shipping updates, or marketing messages with approved templates, are better served by the Business API path rather than Baileys, since that is the route built for verified sending at scale rather than a single linked device.

Compatibility and versioning between OpenClaw, WhatsApp, and your model

Three moving parts have to stay aligned for a WhatsApp integration to keep working: the OpenClaw gateway itself, the WhatsApp Web protocol that Baileys reverse-engineers, and whichever model you have routed the agent to.

WhatsApp Web's protocol is not publicly documented by Meta, so Baileys updates periodically to track changes Meta makes on its end. This means an OpenClaw gateway running an outdated version of the WhatsApp plugin can start failing silently after a protocol change on WhatsApp's side, even though nothing in your own configuration changed. Keeping the gateway and its channel plugins current is the most reliable defense against this class of failure.

Runtime compatibility is a second axis worth tracking separately from protocol compatibility. As covered earlier, OpenClaw's own documentation flags Bun as unreliable for the WhatsApp gateway, so a runtime upgrade or a switch away from Node.js is a legitimate suspect when a previously stable integration starts dropping connections.

Model compatibility is more forgiving: OpenClaw's agent layer is designed to route between many models, so switching providers rarely breaks the WhatsApp connection itself. Where it does matter is response formatting. A model that returns long, unchunked output can interact awkwardly with textChunkLimit and chunkMode settings tuned for a different model's typical output length, so it is worth revisiting chunking configuration after any model change rather than assuming the old settings still fit.

Known limitations of the OpenClaw WhatsApp integration

The Baileys path is unofficial by nature, and that trade-off is worth stating plainly rather than glossing over. Because it reverse-engineers WhatsApp Web rather than using a sanctioned API, it carries some risk of breaking when WhatsApp changes its protocol, and it is not the path Meta intends for business-scale automated messaging.

Linked device limits are a real constraint: WhatsApp caps linked devices at four slots per account, as OpenClaw's integration documentation notes, which limits how many separate tools or gateways can share a single WhatsApp number simultaneously.

Pairing and access approval add friction that other channels do not have. DM access requests can require owner approval and expire within an hour if left unaddressed, according to setup documentation, which means a forgotten approval request simply disappears rather than staying queued.

Media handling has a hard ceiling too: the default 50 MB inbound limit means longer videos or large files get rejected outright rather than partially processed. And because the gateway depends on a single persistent socket connection per account, a reconnect storm, an expired session, or a runtime incompatibility can take the whole WhatsApp line down at once, with no graceful degradation to a backup channel unless you have built one yourself.

None of these are reasons to avoid the integration. They are reasons to plan for them: dedicated numbers, conservative allowFrom defaults, current plugin versions, and a supervised, always-on gateway process address most of the list before it becomes a problem.

Choosing between a quick QR setup and a production WhatsApp Business workflow

Baileys is the right call when you want an assistant talking on WhatsApp this afternoon: no business verification, no template approval queue, just a QR scan. The Business API earns its complexity once you need verified sending, templates, or volume past what one linked device comfortably handles. The real trade-off is not cost, it is time-to-production versus long-term control, and a dedicated number with tight allowFrom defaults keeps either path safer. Managed hosting removes the uptime and reconnect babysitting entirely, which is the part most people underestimate.

> *— Iosif Peterfi*

Running your OpenClaw WhatsApp integration on ClawBase

We built ClawBase to remove exactly the sysadmin work this guide just walked through: provisioning a host, picking a runtime, watching for Bun incompatibilities, and supervising a gateway process so a crash does not take your WhatsApp line down with it. One-click deployment gets a dedicated, encrypted instance running with persistent memory and access to many models, already set up to connect to WhatsApp alongside Telegram, Discord, and Slack.

Clawbase

If you would rather spend your time configuring allowFrom lists and agent behavior than debugging proxy settings at midnight, our pricing page lists current prices and details for plans, with a free trial period available for testing the setup before committing.

FAQ

Can I integrate my AI chatbot with WhatsApp?

Yes, most AI chatbot frameworks, including OpenClaw, connect to WhatsApp either through the unofficial WhatsApp Web client (Baileys) for personal and development use, or through the official Business API for verified business sending. The right path depends on whether you need QR-based speed or business verification and templates.

How can I integrate with the WhatsApp API?

The official WhatsApp Business API integration uses webhooks and access tokens rather than a live socket connection, and it requires business verification through Meta. For OpenClaw specifically, the Baileys path via openclaw channels login --channel whatsapp is the faster alternative when business verification is not required.

Is the WhatsApp API legal?

The official WhatsApp Business API is Meta's sanctioned, legal path for automated business messaging. Baileys-based WhatsApp Web integrations operate in a gray area since they rely on reverse-engineered protocol access rather than an approved API, so production businesses with compliance requirements generally lean toward the official API.

Which CRMs have WhatsApp integration?

Many CRM platforms offer WhatsApp integration through the official Business API, typically for lead routing, order updates, and customer support threads. Compatibility and setup requirements vary by platform, so check each CRM's own documentation for its specific WhatsApp connection method.

Sources

Useful docs and guides for going deeper

Recommended