Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
WhatsApp

WednesdayAI connects to WhatsApp via the WhatsApp Web protocol (Baileys). The gateway owns the linked session and reconnect loop. This is the same mechanism WhatsApp Web uses — you link a WhatsApp number to the gateway, and it sends and receives messages on that number’s behalf.
WhatsApp requires the gateway to run on Node.js (not Bun). Bun is flagged as incompatible for stable WhatsApp operation.

​
Prerequisites

  • A WhatsApp-capable phone number (separate dedicated number recommended)
  • The gateway running on Node.js 22+
  • The phone that holds the WhatsApp account online and reachable during linking
Use a dedicated number for the bot when possible. A personal number adds complexity around self-chat, allowlist management, and number confusion.

​
Quick setup

1. Configure access policy: 
// ~/.openclaw/openclaw.json
{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",          // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123"],  // E.164 numbers allowed to message the bot
    },
  },
}
2. Link the WhatsApp number: 
openclaw channels login --channel whatsapp
Scan the QR code with the WhatsApp app on the phone holding the number. The QR expires after ~2 minutes — if it times out, run the command again. For a named account (multi-account setup): 
openclaw channels login --channel whatsapp --account work
3. Start the gateway and approve pairing requests: 
openclaw gateway run
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Pairing codes expire after 1 hour. Pending requests are capped at 3 per channel. 4. Verify: 
openclaw channels status --channel whatsapp
openclaw status --deep

​
Access control

​
DM policy

dmPolicyEffect
"pairing"New senders get a one-time pairing code; the bot ignores them until you approve (default)
"allowlist"Only numbers in allowFrom can initiate DMs
"open"Any sender allowed (requires allowFrom: ["*"])
"disabled"Bot ignores all DMs
Configure allowFrom with E.164-format numbers: 
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+61400000000"],
    },
  },
}

​
Group policy

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",       // open | allowlist | disabled
      groupAllowFrom: ["+15555550123"],
      groups: {
        "120363000000000000@g.us": true,  // specific group allowlist
      },
    },
  },
}
Group messages require a mention by default. To allow responses without mention: 
{ channels: { whatsapp: { groups: { "*": { requireMention: false } } } } }

​
Multi-account setup

Run multiple WhatsApp numbers from one gateway: 
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      accounts: {
        personal: { authDir: "~/.openclaw/credentials/whatsapp/personal" },
        work: { authDir: "~/.openclaw/credentials/whatsapp/work" },
      },
    },
  },
}
Link each account separately: 
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account work

​
Delivery settings

{
  channels: {
    whatsapp: {
      textChunkLimit: 4000,           // max chars per message chunk
      chunkMode: "length",            // length | newline
      mediaMaxMb: 50,                 // inbound media download cap
      sendReadReceipts: true,
      ackReaction: {
        emoji: "👀",
        direct: "always",             // always | mentions | never
        group: "mentions",
      },
    },
  },
}

​
Credentials and storage

WhatsApp credentials are stored at ~/.openclaw/credentials/whatsapp/<accountId>/creds.json. 
# Check credential freshness
ls -l ~/.openclaw/credentials/whatsapp/default/creds.json
A recent mtime indicates the session is active. A stale or missing file means the channel is logged out.

​
Disabling without removing config

{ channels: { whatsapp: { enabled: false } } }
Restart the gateway to take effect: systemctl --user restart openclaw-gateway

​
Troubleshooting

openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp --verbose
The phone must be online and connected to the internet. The QR times out after ~2 minutes.
A conflicting WhatsApp Web session is open. Close all other WhatsApp Web browser sessions, then relink:
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp
Status 515 auto-retries once after pairing — this is normal.
Check in order:
  1. groupPolicy is "open" or "allowlist" with the group in groups
  2. groupAllowFrom includes the sender (or falls back to allowFrom)
  3. Mention requirement: requireMention: false in groups config, or the message mentions the bot
  4. No duplicate keys in openclaw.json (check with openclaw doctor)
The gateway is not running or the WhatsApp account is not linked.
openclaw gateway status
openclaw channels status --channel whatsapp