Multiple WhatsApp Numbers

+15 Mana ✨
OpenClaw Channel Configuration(DOCUMENTATION)

Introduction

OpenClaw supports connecting multiple WhatsApp phone numbers to a single gateway, each bound to a different agent. This pattern is essential for businesses that need separate WhatsApp lines for different departments, regions, or client segments.

Key Concepts

  • Channel Login: The openclaw channels login command authenticates a new channel account, such as a WhatsApp phone number.
  • Account Binding: Each WhatsApp number gets a unique accountId that can be bound to a specific agent via the routing configuration.
  • QR Code Authentication: WhatsApp uses QR code scanning to link a phone number to the gateway.
  • Multi-Number Isolation: Each WhatsApp number maintains its own message queue, session history, and contact list.

Real World Context

A multinational support team uses one WhatsApp number for US customers and another for EU customers. Each number routes to a different agent with region-specific knowledge, language preferences, and compliance rules. The US agent knows US tax regulations while the EU agent understands GDPR requirements. Both run on the same gateway but never see each other's conversations.

Deep Dive

To add a second WhatsApp number, use the channel login command:

bash
# Add first WhatsApp number
openclaw channels login whatsapp --label "US Support"
# Scan QR code with the US support phone

# Add second WhatsApp number
openclaw channels login whatsapp --label "EU Support"
# Scan QR code with the EU support phone

# List connected accounts
openclaw channels list

The --label flag gives each account a human-readable name for identification. After scanning the QR codes, both numbers appear in the channel list with unique accountIds.

Next, bind each account to its agent in the gateway configuration:

json
{
  "agents": {
    "us-support": {
      "bindings": [
        {
          "type": "account",
          "accountId": "whatsapp:us-support-number"
        }
      ]
    },
    "eu-support": {
      "bindings": [
        {
          "type": "account",
          "accountId": "whatsapp:eu-support-number"
        }
      ]
    }
  }
}

This configuration routes messages from the US WhatsApp number to the us-support agent and messages from the EU number to the eu-support agent. Each agent has its own workspace with region-specific instructions and memory.

Common Pitfalls

  1. Using the same phone for two accounts — Each phone number can only be linked to one WhatsApp Web session at a time. Trying to link the same number twice will disconnect the first session.
  2. Forgetting to bind new accounts — A newly added WhatsApp number without a binding falls through to the default agent, which may not have the right context.

Best Practices

  1. Use descriptive labels — Labels like "US Support" and "EU Support" are much easier to manage than auto-generated IDs.
  2. Test each number independently — After setup, send a test message to each number to verify routing works as expected.

Summary

  • Each WhatsApp number is added via openclaw channels login whatsapp with a unique label
  • Numbers get unique accountIds that can be bound to specific agents
  • QR code authentication links each phone to the gateway
  • Each number maintains its own message queue and session history
  • Always bind new accounts to agents to avoid unintended routing to the default agent
✓ Completed