← Back to Agent
WhatsApp Business
Connect a dedicated business phone number for customer support via WhatsApp — separate from your personal messaging.
Overview
For Everyone
The WhatsApp Business tab lets your agent handle customer support via WhatsApp. Customers message a phone number and your AI agent responds automatically. You can use a dedicated business number or share your personal WhatsApp — the agent recognizes your manager number and gives you priority. Features include customer pairing codes, prompt injection protection, rate limiting, and a full conversation viewer.
For Developers
WhatsApp Business config is stored in config.messagingChannels.whatsapp.business. The connection uses the Baileys WhatsApp Web library via /bridge/agents/:id/whatsapp/connect with mode=business. QR code scanning is polled every 3 seconds until connection succeeds. Customer pairing uses /whatsapp/pairing-requests and /whatsapp/pairing-approve endpoints. Conversations are paginated via /whatsapp/conversations.
How It Works
- Choose a connection mode — same number (share your personal WhatsApp) or separate number (dedicated business phone).
- For separate number: scan a QR code with the business phone's WhatsApp (Settings → Linked Devices).
- Set your manager phone number so the agent recognizes you.
- Enable business mode to accept customer messages.
- Configure customer DM policy — pairing (recommended), open, or closed.
- Set up security — prompt injection detection, message blocking, tool restrictions, rate limits.
Connection Modes
Two approaches to connect WhatsApp for business use:
| Mode | Description | Best For |
|---|
| Same Number | Uses your personal WhatsApp connection from the Channels tab. Agent recognizes your manager number and treats everyone else as customers. | Simplicity, solo operators, getting started quickly |
| Separate Number | Dedicated business phone number with its own QR connection. Your personal WhatsApp stays private. | Clear separation, teams, professional appearance |
Same Number Mode
Toggle "Use same phone number for both" to enable. In this mode:
- Your personal WhatsApp connection (from the Channels tab) is shared for business.
- Messages from your manager phone number get priority — even with 10 active customer chats.
- Everyone else is treated as a customer (if business mode is enabled).
- No separate QR scan needed — just ensure your personal connection is active in Channels.
Required: Set your manager phone number below so the agent can identify you. Without it, the agent can't distinguish you from customers.
Separate Number Mode
Setup guide for a dedicated business number:
- Get a phone number — A new SIM, Google Voice, or existing WhatsApp Business number.
- Register on WhatsApp — Install WhatsApp on a phone with that number and set up the account.
- Scan the QR code — Click "Connect Business Number", then scan the QR code from WhatsApp → Settings → Linked Devices → Link a Device.
Once connected, you can send test messages and toggle business mode on/off.
Customer Access & Pairing
DM Policies
| Policy | Description |
|---|
| Pairing Recommended | New customers receive a pairing code. You approve or reject from the dashboard. Most secure. |
| Open | Anyone can message and the agent responds. Use with strong security settings. |
| Closed | No new customers. Only previously approved customers can message. |
Pairing Flow
When a new customer messages (in pairing mode):
- Customer sends a message → receives an auto-reply with a pairing code.
- The request appears in Pending Customer Requests with name, phone, code, and timestamp.
- You click Approve or Reject.
- Approved customers are added to the Approved Customers list and can chat freely.
Security & Prompt Injection Protection
Customer messages are treated as untrusted external content. Security features:
| Setting | Default | Description |
|---|
| Prompt injection detection | On | Scans messages for known injection patterns ("ignore previous instructions", etc.). Suspicious messages are flagged and logged. |
| Block suspicious messages | Off | Messages matching multiple injection patterns are blocked with a generic reply. |
| Restrict customer tools | On | Limits which tools the agent can use during customer conversations. Prevents customers from tricking the agent into accessing files, running commands, or sending emails. |
| Max message length | 2000 | Messages longer than this are truncated. |
| Rate limit | 10 msgs/min/sender | Prevents spam and brute-force attempts. |
Customer Experience Settings
- Greeting Message — Sent to newly approved customers on first interaction. Leave empty for natural response.
- Auto-Reply to Unknown Senders — Shown briefly before the pairing code.
- Custom Instructions — Additional system prompt for customer conversations. Define brand voice, what to discuss/avoid, and business rules.
- Business Hours — Managed in the Workforce tab. The agent respects those settings automatically.
Conversations
When business mode is active, a full Conversations section appears with:
- Search — Find conversations by name, number, or message content.
- Filters — All messages, customer messages only, or agent replies only.
- Conversation list — Shows avatar, name, last message, timestamp, message counts, and trust/customer badges.
- Conversation detail — Click any conversation to view the full message history with a chat-style interface (agent messages on the right, customer on the left). Load older messages with pagination.
Client Organization Context
When an agent belongs to a client organization, an info banner appears indicating which organization the agent serves. This affects WhatsApp Business in several ways:
- The business WhatsApp number is labeled as the organization's business line.
- Customer pairing requests note which organization the customer will be paired with, providing clarity in multi-org environments.
- Greeting messages and auto-replies should reference the organization's brand, not the platform's.
- Conversation logs are scoped to the organization for reporting and compliance purposes.
Tip: When writing custom instructions for customer conversations, reference the organization name and brand guidelines to maintain consistency.
Key Concepts
- Business Mode — The master toggle for accepting customer messages. Without it, only trusted contacts can reach the agent.
- Manager Number — Your phone number. Messages from this number always get priority and bypass customer restrictions.
- Customer Pairing — A verification flow where new customers receive a code and await admin approval.
- Prompt Injection — Attempts by users to manipulate the AI by embedding instructions in their messages (e.g., "ignore all previous instructions and...").
- Tool Restrictions — Limits the agent's capabilities during customer conversations to prevent exploitation.
Best Practices
- Start with same-number mode for simplicity. Switch to separate number when you need clear separation.
- Always use pairing mode for customer access unless you have a specific reason for open access.
- Enable prompt injection detection — it's on by default for good reason.
- Set a reasonable rate limit — 10 msgs/min prevents abuse without annoying legitimate customers.
- Write custom instructions — Tell the agent exactly what it should and shouldn't discuss with customers.
- Monitor conversations regularly — Check the conversation viewer for quality and any issues.
Troubleshooting
| Problem | Solution |
|---|
| QR code won't scan | Ensure WhatsApp is updated. Try refreshing the QR code. The code expires after ~60 seconds. |
| Connection drops frequently | WhatsApp Web connections can be unstable. The system auto-reconnects. Check the business phone's internet connection. |
| Agent not responding to customers | Verify business mode is enabled. Check the customer's DM policy — they may need to be approved first (pairing mode). |
| Same number mode: agent can't tell who's the manager | Ensure the manager phone number is set and matches exactly (including country code, e.g., +1234567890). |
| Messages being blocked incorrectly | Lower the prompt injection sensitivity or disable "Block suspicious messages." Check the agent's logs for false positives. |
Channels — Personal WhatsApp and Telegram messaging setup.
Email — Email account connection for the agent.
Permissions — Rate limits and tool restrictions.
Tools — Enable/disable messaging tools.