The WhatsApp channel gateway turns your WhatsApp account into a conversational interface for Polpo. Send messages, run commands, approve tasks, and manage your project — all from WhatsApp.
This integration uses the unofficial WhatsApp Web protocol via Baileys. It is intended for personal use only. For production/business use, implement the official WhatsApp Business API instead. Use at your own risk. This page covers interactive messaging (talking to Polpo via WhatsApp). For one-way notification delivery (Polpo sending you alerts), see WhatsApp Notifications. Setup
-
Link your WhatsApp account by scanning a QR code:
Scan the QR code displayed in your terminal using WhatsApp on your phone (Settings > Linked Devices > Link a Device).
-
Configure the gateway in
polpo.json:
{
"settings": {
"notifications": {
"channels": {
"whatsapp": {
"type": "whatsapp",
"gateway": {
"enableInbound": true,
"dmPolicy": "allowlist",
"allowFrom": ["39123456789"]
}
}
}
}
}
}
-
Start Polpo — the gateway activates automatically:
Gateway Configuration
The gateway object on the WhatsApp channel enables inbound messaging:
| Field | Type | Default | Description |
|---|
enableInbound | boolean | false | Enable the conversational gateway |
dmPolicy | string | "allowlist" | Who can message: open, allowlist, pairing, disabled |
allowFrom | string[] | [] | Phone numbers or peer IDs allowed to message. Use ["*"] for everyone |
sessionIdleMinutes | number | 60 | Auto-reset session after idle period |
DM Policies
Control who can interact via WhatsApp:
| Policy | Behavior |
|---|
open | Anyone who messages you can interact with Polpo |
allowlist | Only users in allowFrom or the dynamic allowlist |
pairing | Unknown users get a pairing code; an admin approves to grant access |
disabled | Inbound messages are silently ignored |
Slash Commands
Send these as WhatsApp messages:
| Command | Description |
|---|
/help | Show all available commands |
/status | Project status — task counts, active agents, connected peers |
/tasks | List tasks with status |
/missions | List missions |
/agents | List agents with active/idle status |
/approve [ID] | List pending approvals, or approve a specific one |
/reject ID [reason] | Reject an approval with feedback |
/new | Reset your conversation session |
/pair CODE | Approve a pairing request (admin only) |
Free-Text Chat
Any message that isn’t a slash command is routed to Polpo’s agentic completions loop. You can ask questions, create tasks, get status updates, and request code changes — just like with the Telegram gateway.
Each peer gets their own conversation session with history preserved across messages. Sessions auto-reset after the configured idle period (default: 60 minutes), or manually with /new.
CLI Commands
Manage the WhatsApp connection from the command line:
| Command | Description |
|---|
polpo whatsapp login | Link device via QR code scan |
polpo whatsapp status | Check connection and auth status |
polpo whatsapp logout | Remove stored credentials and disconnect |
Peer Identity
Each WhatsApp user is identified by their phone number: whatsapp:{phoneNumber} (e.g. whatsapp:39123456789). You can link WhatsApp and Telegram identities to share sessions across channels — see Peer Identity.
Example Configurations
Personal Use (open)
{
"gateway": {
"enableInbound": true,
"dmPolicy": "open"
}
}
Allowlist
{
"gateway": {
"enableInbound": true,
"dmPolicy": "allowlist",
"allowFrom": ["39123456789", "44987654321"]
}
}
With "dmPolicy": "open", anyone who messages your WhatsApp number can interact with Polpo and control your agents. Use allowlist or pairing for any non-personal deployment.
