Spaces:
Running
Running
| # WhatsApp Integration Plugin | |
| Communicate with Agent Zero via WhatsApp using a Baileys-based Node.js bridge. | |
| ## Requirements | |
| - **Node.js** (v18+) and npm installed on the system | |
| - A WhatsApp account on a phone (for QR code pairing) | |
| ## Setup | |
| ### Install bridge dependencies | |
| ```bash | |
| cd plugins/_whatsapp_integration/whatsapp-bridge | |
| npm install --production | |
| ``` | |
| Dependencies are auto-installed on first bridge start if missing. | |
| ### Configure and pair | |
| 1. Enable the plugin in Settings > External > WhatsApp Integration | |
| 2. Configure allowed phone numbers | |
| 3. Click Show QR Code and scan with WhatsApp on your phone | |
| 4. Send a message from an allowed number to start a chat | |
| 5. Use `/project <name>`, `/config <preset>`, or `/send` in WhatsApp to control the active chat directly | |
| The WhatsApp session persists across restarts in `tmp/whatsapp/session/`. No re-pairing needed unless you disconnect via settings. | |
| Be careful: if you use your personal number and leave `allowed_numbers` open, other people could misuse your Agent Zero. | |
| ## Configuration | |
| | Setting | Description | Default | | |
| |---------|-------------|---------| | |
| | `enabled` | Enable bridge and polling | `false` | | |
| | `mode` | `self-chat` (personal number) or `dedicated` (separate number) | `self-chat` | | |
| | `allow_group` | Respond in group chats when mentioned or replied to | `false` | | |
| | `bridge_port` | Local HTTP port for bridge | `3100` | | |
| | `poll_interval_seconds` | Poll frequency (min 2) | `3` | | |
| | `allowed_numbers` | Phone numbers without + prefix | `[]` (all) | | |
| | `project` | Activate project for WA chats | `""` | | |
| | `agent_instructions` | Extra agent instructions | `""` | | |
| ## How It Works | |
| 1. The bridge connects to WhatsApp via Baileys and exposes HTTP endpoints on localhost | |
| 2. In personal-number mode, you can message your own WhatsApp number to talk to the agent, and the agent can also handle messages that other people send to that number | |
| 3. The plugin polls the bridge for new messages every few seconds | |
| 4. Incoming messages are routed to existing chats by WhatsApp chat ID or new chats are created | |
| 5. Agent responses are sent back via the bridge as WhatsApp messages | |
| 6. Media (images, documents) is supported in both directions | |
| ## Architecture | |
| ``` | |
| WhatsApp Phone | |
| ↕ (WhatsApp protocol via Baileys) | |
| whatsapp-bridge/bridge.js (Node.js subprocess) | |
| ↕ (HTTP API on localhost) | |
| Python helpers (wa_client, handler, bridge_manager) | |
| ↕ (Framework extensions) | |
| Agent Zero | |
| ``` | |