WhatsApp Channel Settings: Every Option Explained

Your Bot It Out agent can communicate through WhatsApp, but the default settings might not match your use case. This guide walks through every WhatsApp configuration option so you can set up the right access controls for your agent.

Two Layers of WhatsApp Setup

Before diving into settings, it helps to understand that WhatsApp on Bot It Out has two layers:

1. Device Linking — connects a WhatsApp phone number to your instance. This is the QR code scan step. One phone number can only be linked to one instance at a time. If you want multiple agents on WhatsApp, you need a separate phone number for each.

2. Channel Configuration — controls how the agent uses that linked number. Who can message it, how it behaves in groups, and what triggers a response. This is where the real customization happens.

Unlinking the device removes the WhatsApp session entirely — you would need to scan a new QR code to reconnect. Removing the channel configuration stops the agent from routing messages through WhatsApp, but the phone number stays linked to the instance.

DM Access Policies

When someone sends a direct message to your agent's WhatsApp number, the DM policy decides what happens. There are four options.

Pairing Code (Recommended for Most Use Cases)

The pairing code policy is the most secure option that still allows new contacts. When an unknown number messages your agent for the first time, they receive an 8-character pairing code. You approve or deny that code via SSH on your instance:

• openclaw pairing approve whatsapp CODE

Until you approve the code, the agent won't respond to that person. Once approved, they can message freely going forward. This gives you full control over who gets access without having to know their phone number in advance.

Best for: Customer support bots where you want to verify users before granting access. Internal company bots where employees self-register. Any scenario where you want a human gatekeeper.

Allowlist Only

The allowlist restricts the agent to a specific set of phone numbers you define upfront. Only those numbers can message the agent — everyone else is silently ignored.

Phone numbers must be in E.164 format with the country code: +15551234567, +972501234567.

Best for: Private agents serving a known, fixed group of users. Family or small team bots. Agents that should only respond to specific clients.

Open to All

Anyone who has your agent's WhatsApp number can message it and get a response. No verification, no restrictions.

Best for: Public-facing customer support where you want zero friction. Marketing bots where anyone should be able to interact. Demo or trial agents you are sharing broadly.

Warning: Open mode means anyone with the number can use your agent's tokens. Consider this carefully for agents using expensive models.

Disabled

The agent ignores all direct messages on WhatsApp. This is useful when you only want the agent active in group chats, or when you want to temporarily pause DM access without removing the WhatsApp channel entirely.

Best for: Group-only bots. Temporarily pausing DM access during maintenance.

Group Chat Settings

WhatsApp group chats have their own set of controls, independent of DM settings. You can have DMs open but groups disabled, or vice versa.

Group Policy

Disabled — The agent does not respond in any group chat. Even if added to a group, it stays silent.

Allowlist — Only messages from specific phone numbers trigger the agent in groups. Other group members are ignored. Useful when you want the bot in a group but only certain people should be able to use it.

Open — Anyone in the group can trigger the agent.

Group Activation Mode

When group chat is enabled (allowlist or open), you also choose how the agent gets activated:

Mention Only — The agent only responds when directly @mentioned or when someone replies to one of its messages. It sees all messages in the group but stays quiet unless explicitly called on. This is the less intrusive option and works well in active groups where the bot shouldn't dominate the conversation.

Always Active — The agent reads every message and responds when it thinks it is relevant. This is more aggressive and uses more tokens, but useful for groups where the agent should proactively participate.

Custom Mention Patterns

When using Mention Only activation, the agent always responds to native WhatsApp @mentions and direct replies. But you can also define custom trigger words — text patterns that activate the agent even without an @mention.

For example, if your agent is a sales assistant, you might set trigger words like: sales-bot, hey sales, @sales

Comma-separated, case-insensitive. The agent checks each group message for these patterns and responds if any match.

Best for: Groups where @mentioning is inconvenient. Agents with a specific "name" that people naturally use in conversation.

Common Configuration Examples

Here are some real-world setups to get you started:

Personal Assistant Bot

• DM Policy: Allowlist (just your number)
• Group Policy: Disabled
• Why: Only you should be able to message it. No group exposure.

Customer Support Bot

• DM Policy: Open to All
• Group Policy: Disabled
• Why: Customers should reach you without friction. No group use needed.

Team Workspace Bot

• DM Policy: Pairing Code
• Group Policy: Open, Mention Only
• Mention Patterns: hey bot, @assistant
• Why: Team members self-register via pairing. In group chats, the bot responds when called.

Community Moderator Bot

• DM Policy: Disabled
• Group Policy: Open, Always Active
• Why: The bot lives in the group, monitors conversation, and responds proactively. No DMs needed.

VIP Client Bot

• DM Policy: Allowlist (client numbers)
• Group Policy: Allowlist (same clients), Mention Only
• Why: Only approved clients interact with the agent, in DMs or groups.

One Number, One Instance

A WhatsApp number can only be linked to one Bot It Out instance at a time. If you need multiple agents on WhatsApp — say a support bot and a sales bot — you need a separate phone number for each.

Get a Dedicated Number for Your Agent

We strongly recommend getting a real, dedicated phone number for each agent rather than using your personal number. Here's why:

Professionalism. When customers message your support agent, they should see a business-like contact name — "Acme Support" or "Sales Bot" — not your personal name and photo. A dedicated number lets you set up a clean WhatsApp profile with your company logo, a proper display name, and a business description.

Separation. Your personal WhatsApp stays personal. No mixing of business messages with family chats. No risk of accidentally exposing personal conversations or contacts.

Scalability. When you add a second agent later, you already have the pattern in place — one number per agent, each with its own identity.

How to get a number:

• A prepaid SIM card from any carrier works. Most countries have options for under $5/month. Insert it into a spare phone, verify WhatsApp, then scan the QR code from your Bot It Out dashboard.
• Some carriers offer virtual numbers or eSIMs that work with WhatsApp — no physical phone needed after initial setup.
• For businesses, consider a dedicated business line. Some VoIP providers offer numbers that work with WhatsApp Business API, though for Bot It Out's device linking flow, a standard WhatsApp number is all you need.

Pro tip: Name the WhatsApp contact something descriptive. Your customers will see this name when they message the bot. "Acme Customer Support" is better than "Bot 1".

Changing Settings

You can update WhatsApp channel settings at any time from your instance dashboard without relinking the device. Changes take effect within a few seconds after the gateway restarts.

To fully remove WhatsApp, you have two options:

• Remove Channel — stops message routing but keeps the device linked. You can re-enable later without scanning a new QR code.
• Unlink Device — removes the WhatsApp Web session entirely. You will need to scan a new QR code to reconnect.