vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-07-09 17:08:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
agent-zero/plugins/_whatsapp_integration
History
frdel e138e33ca9 Add file-level DOX docs & update AGENTS indexes 
Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps.
2026-06-08 12:41:53 +02:00
..
api ui: redesign email, Telegram, and WhatsApp settings 2026-04-11 01:40:24 +02:00
extensions/python Squashed commit of the following: 2026-03-31 09:47:25 +02:00
helpers integrations: add native chat controls and email config presets 2026-04-11 18:49:13 +02:00
prompts Add sender number to WhatsApp user message format 2026-05-15 19:45:30 -04:00
webui fix integration config UI persistence for Telegram + WhatsApp 2026-04-21 06:01:36 +02:00
whatsapp-bridge Squashed commit of the following: 2026-03-31 09:47:25 +02:00
AGENTS.md Add file-level DOX docs & update AGENTS indexes 2026-06-08 12:41:53 +02:00
default_config.yaml Squashed commit of the following: 2026-03-31 09:47:25 +02:00
plugin.yaml Squashed commit of the following: 2026-03-31 09:47:25 +02:00
README.md integrations: add native chat controls and email config presets 2026-04-11 18:49:13 +02:00

README.md

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

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