WAHA (WhatsApp HTTP API)

OpenClaw WAHA channel plugin. Alternative WhatsApp integration via WhatsApp HTTP API.

The WAHA plugin is the most comprehensive WhatsApp integration available for OpenClaw, providing access to 87%+ of the WAHA (WhatsApp HTTP API) surface area. Unlike OpenClaw's built-in WhatsApp channel which relies on basic pairing-code connectivity, this plugin unlocks the full spectrum of WhatsApp capabilities — groups, channels, newsletters, polls, reactions, stickers, voice messages, contact cards, labels, status/stories, presence management, and much more. Architecturally, the plugin runs a webhook server alongside the OpenClaw gateway that receives events from a self-hosted WAHA instance (a Docker container that wraps WhatsApp Web). It features production-grade reliability with request timeouts, token-bucket rate limiting, automatic retry with exponential backoff, and webhook deduplication. The built-in inbound message queue prevents message loss under load with separate DM and group queues. Session health monitoring via automatic pings detects disconnects before they affect message delivery. One of the plugin's standout features is its human mimicry system — realistic typing indicators, read receipts, and configurable random pauses that make the bot feel natural in conversations. The multi-session architecture lets you run a bot session alongside a human session with layered guardrails and role-based access control. Cross-session routing is automatic, and messages sent through a human session are prefixed with a robot emoji so recipients know it's the bot. The plugin includes a built-in admin panel (web UI) with real-time monitoring, a directory browser for contacts and groups, a config editor, and session health displays. A file-based YAML rules system enables per-contact and per-group behavior control without code changes. With over 1,300 weekly downloads and active development (v1.16+), it's the go-to choice for anyone who needs more than basic WhatsApp messaging from their OpenClaw agent.

Tags: channel, messaging, whatsapp

Use Cases

  • Full-featured WhatsApp AI assistant with group support, polls, reactions, and media handling
  • Multi-session setup: bot handles automated tasks while human session monitors conversations
  • Automated WhatsApp status/story posting for social media management
  • Customer support bot with per-contact behavior rules and group allowlisting
  • WhatsApp-based task management with label organization and contact card sharing
  • Automated group management — create groups, add/remove participants, promote admins

Tips

  • Use dmPolicy: 'pairing' for a safe default that requires users to pair before the bot responds
  • Set godModeScope to 'dm' instead of 'all' in multi-session setups to prevent accidental group responses
  • Enable human mimicry (presence simulation) to make the bot feel natural — configurable WPM, read delays, and typing duration
  • Use the built-in /shutup command in groups to mute the bot temporarily without config changes
  • Set up the admin panel at http://HOST:8050/admin for real-time monitoring and directory management
  • Use YAML rules files for per-contact and per-group behavior control without restarting the gateway
  • For production deployments, set webhookHmacKey to enable HMAC-SHA512 webhook signature verification
  • Auto name resolution lets you send messages using human-readable names instead of JIDs

Known Issues & Gotchas

  • tools.alsoAllow: ['message'] is MANDATORY — without it the AI agent cannot invoke any WhatsApp actions
  • You must point your WAHA session's webhook to the plugin's webhook URL (http://HOST:8050/webhook/waha)
  • Both @c.us and @lid JID formats must be included in allowFrom/groupAllowFrom lists
  • WAHA free tier only supports a single session — multi-session requires WAHA Plus license
  • The admin panel runs on the same port as webhooks (8050) — don't block it with a firewall
  • WhatsApp can ban your number if you send too many automated messages too fast — use the rate limiter
  • God mode scope 'all' bypasses all filters — use 'dm' for multi-session setups to avoid the bot responding uninvited in groups
  • Cross-session dedup gives the bot session 200ms priority — if both sessions receive the same message, only one processes it

Alternatives

  • Built-in WhatsApp Channel
  • WhatsApp Business API (official)
  • Evolution API

Community Feedback

WAHA is a very helpful tool that emulates WhatsApp Web and allows you to send messages to anyone. It's open source and I have used it in production for months.

— Reddit r/selfhosted

Do you think OpenClaw using unofficial WhatsApp APIs was a lost business opportunity for Meta? Nothing says we need official APIs like a million people using unofficial ones.

— Reddit r/WhatsappBusinessAPI

The most comprehensive WhatsApp integration for OpenClaw. Full WhatsApp API access through WAHA — groups, channels, media, polls, reactions, stickers, voice messages, contact cards, labels.

— jsDelivr

Frequently Asked Questions

What is WAHA and why do I need it for this plugin?

WAHA (WhatsApp HTTP API) is a self-hosted Docker container that wraps WhatsApp Web into a REST API. This plugin connects OpenClaw to WAHA, giving your AI agent full WhatsApp capabilities. You need to run WAHA separately — the plugin just bridges the two systems.

How is this different from OpenClaw's built-in WhatsApp channel?

The built-in channel uses basic pairing-code connectivity with limited features. The WAHA plugin covers 87%+ of the WhatsApp API — groups, polls, reactions, stickers, labels, status/stories, presence management, and an admin panel. It's the full-featured option.

Will WhatsApp ban my number for using WAHA?

There's always a risk when using unofficial WhatsApp APIs. To minimize it, use the built-in rate limiter, enable human mimicry for natural typing patterns, and avoid bulk messaging. Many users run WAHA in production without issues, but it's not officially sanctioned by Meta.

Can I run multiple WhatsApp sessions simultaneously?

Yes, the plugin supports multi-session with role-based access control. You can run a bot session (full-access) alongside a human session (listener or full-access). Cross-session deduplication ensures messages aren't processed twice. WAHA Plus license is required for multi-session on the WAHA side.

Why can't my AI agent send WhatsApp messages?

The most common issue: you're missing tools.alsoAllow: ['message'] in your OpenClaw config. Without it, the coding tools profile filters out the message tool and the AI cannot invoke any WhatsApp actions. This is mandatory and easily overlooked.

Does the WAHA plugin support WhatsApp groups?

Yes, extensively. It supports creating groups, managing participants, promoting/demoting admins, setting group policies, and filtering messages per-group. You can use groupPolicy to control which groups the bot responds in, and the /shutup command lets anyone mute the bot in a specific group.

Configuration Examples

Basic single-session setup

channels:
  waha:
    enabled: true
    baseUrl: http://localhost:3000
    apiKey: YOUR_WAHA_API_KEY
    session: default
    webhookPort: 8050
    webhookPath: /webhook/waha
    dmPolicy: pairing
    groupPolicy: allowlist

tools:
  alsoAllow:
    - message

Multi-session bot + human setup

channels:
  waha:
    accounts:
      bot:
        baseUrl: http://localhost:3000
        apiKey: YOUR_API_KEY
        session: bot_session
        role: bot
        subRole: full-access
      human:
        baseUrl: http://localhost:3000
        apiKey: YOUR_API_KEY
        session: human_session
        webhookPort: 8051
        role: human
        subRole: listener
        triggerWord: "!"
        triggerResponseMode: reply-in-chat
        dmFilter:
          enabled: true
          godModeScope: dm
        groupFilter:
          enabled: true
          godModeScope: dm
    defaultAccount: bot

Production-hardened configuration

channels:
  waha:
    enabled: true
    baseUrl: http://waha.internal:3000
    apiKey: YOUR_API_KEY
    session: production
    webhookPort: 8050
    webhookHmacKey: your-hmac-secret
    rateLimitCapacity: 20
    rateLimitRefillRate: 15
    healthCheckIntervalMs: 60000
    dmQueueSize: 100
    groupQueueSize: 50
    presence:
      enabled: true
      sendSeen: true
      wpm: 42
      readDelayMs: [500, 4000]
      typingDurationMs: [1500, 15000]
      pauseChance: 0.3

Installation

openclaw plugins install waha-openclaw-channel