| 1 | # WhatsApp Integration Plugin |
| 2 | |
| 3 | Communicate with Agent Zero via WhatsApp using a Baileys-based Node.js bridge. |
| 4 | |
| 5 | ## Requirements |
| 6 | |
| 7 | - **Node.js** (v18+) and npm installed on the system |
| 8 | - A WhatsApp account on a phone (for QR code pairing) |
| 9 | |
| 10 | ## Setup |
| 11 | |
| 12 | ### Install bridge dependencies |
| 13 | |
| 14 | ```bash |
| 15 | cd plugins/_whatsapp_integration/whatsapp-bridge |
| 16 | npm install --production |
| 17 | ``` |
| 18 | |
| 19 | Dependencies are auto-installed on first bridge start if missing. |
| 20 | |
| 21 | ### Configure and pair |
| 22 | |
| 23 | 1. Enable the plugin in Settings > External > WhatsApp Integration |
| 24 | 2. Configure allowed phone numbers |
| 25 | 3. Click Show QR Code and scan with WhatsApp on your phone |
| 26 | 4. Send a message from an allowed number to start a chat |
| 27 | 5. Use `/project <name>`, `/config <preset>`, or `/send` in WhatsApp to control the active chat directly |
| 28 | |
| 29 | The WhatsApp session persists across restarts in `tmp/whatsapp/session/`. No re-pairing needed unless you disconnect via settings. |
| 30 | Be careful: if you use your personal number and leave `allowed_numbers` open, other people could misuse your Agent Zero. |
| 31 | |
| 32 | ## Configuration |
| 33 | |
| 34 | | Setting | Description | Default | |
| 35 | |---------|-------------|---------| |
| 36 | | `enabled` | Enable bridge and polling | `false` | |
| 37 | | `mode` | `self-chat` (personal number) or `dedicated` (separate number) | `self-chat` | |
| 38 | | `allow_group` | Respond in group chats when mentioned or replied to | `false` | |
| 39 | | `bridge_port` | Local HTTP port for bridge | `3100` | |
| 40 | | `poll_interval_seconds` | Poll frequency (min 2) | `3` | |
| 41 | | `allowed_numbers` | Phone numbers without + prefix | `[]` (all) | |
| 42 | | `project` | Activate project for WA chats | `""` | |
| 43 | | `agent_instructions` | Extra agent instructions | `""` | |
| 44 | |
| 45 | ## How It Works |
| 46 | |
| 47 | 1. The bridge connects to WhatsApp via Baileys and exposes HTTP endpoints on localhost |
| 48 | 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 |
| 49 | 3. The plugin polls the bridge for new messages every few seconds |
| 50 | 4. Incoming messages are routed to existing chats by WhatsApp chat ID or new chats are created |
| 51 | 5. Agent responses are sent back via the bridge as WhatsApp messages |
| 52 | 6. Media (images, documents) is supported in both directions |
| 53 | |
| 54 | ## Architecture |
| 55 | |
| 56 | ``` |
| 57 | WhatsApp Phone |
| 58 | ↕ (WhatsApp protocol via Baileys) |
| 59 | whatsapp-bridge/bridge.js (Node.js subprocess) |
| 60 | ↕ (HTTP API on localhost) |
| 61 | Python helpers (wa_client, handler, bridge_manager) |
| 62 | ↕ (Framework extensions) |
| 63 | Agent Zero |
| 64 | ``` |