WhatsApp Adapter

Two WhatsApp adapters are available:

• WhatsAppAdapter — WhatsApp Business Cloud API (official, requires an approved Meta Business account)
• WhatsAppBaileysAdapter — Baileys (unofficial, works with personal numbers via WhatsApp Web emulation)

Both adapters are included in the same install extra:

pip install agentix[gateway-whatsapp]

---

WhatsApp Business API

from agentix.gateway.adapters.whatsapp import WhatsAppAdapter

gateway.add_channel(
    WhatsAppAdapter(
        phone_number_id="...",   # WhatsApp Business phone number ID
        access_token="...",      # Meta Graph API access token
        verify_token="...",      # webhook verification token (you choose)
        app_secret="...",        # Meta app secret for request signature verification
    )
)

All four fields are required. app_secret is validated at construction — an empty value raises ValueError immediately.

Optional field

Parameter	Default	Description
api_version	"v21.0"	Meta Graph API version string

YAML config

channels:
  whatsapp:
    type: whatsapp
    phone_number_id: "${WA_PHONE_NUMBER_ID}"
    access_token: "${WA_ACCESS_TOKEN}"
    verify_token: "${WA_VERIFY_TOKEN}"
    app_secret: "${WA_APP_SECRET}"

Webhook endpoints

• GET /whatsapp/webhook — webhook verification (Meta sends a challenge)
• POST /whatsapp/webhook — incoming messages

---

WhatsApp via Baileys

Unofficial API — Ban Risk

WhatsApp does not officially support third-party bots outside the Business API. Using a third-party bridge carries a small risk of account restrictions. To minimise risk:

• Use a dedicated phone number for the bot — not your personal number
• Keep usage conversational — do not send bulk or unsolicited messages
• Only respond to people who message the bot first; do not automate outbound messaging

WhatsApp Web Protocol Updates

WhatsApp periodically updates their Web protocol, which can temporarily break compatibility with third-party bridges. When this happens, Agentix will update the bridge dependency. If the bot stops working after a WhatsApp update, pull the latest Agentix version and re-pair by scanning a new QR code.

Two modes

Mode	How it works	Best for
Separate bot number (recommended)	Dedicate a phone number to the bot. Users message that number directly.	Clean UX, multiple users, lower ban risk
Personal self-chat	Use your own WhatsApp. You message yourself to talk to the agent.	Quick setup, single user, testing

Set the mode via the mode parameter: "bot" for a dedicated number, "self-chat" for personal use (default).

Prerequisites

• Node.js v18+ and npm — the WhatsApp bridge runs as a Node.js sidecar process
• A phone with WhatsApp installed — for scanning the QR code on first run
• No Chromium or Puppeteer dependency — unlike older browser-driven bridges, the Baileys bridge does not require a local browser stack

Baileys emulates WhatsApp Web. Python dependencies are installed automatically via npm on first run (auto_install_deps=True).

from agentix.gateway.adapters.whatsapp_baileys import WhatsAppBaileysAdapter

gateway.add_channel(
    WhatsAppBaileysAdapter()
    # auth_dir defaults to <cwd>/.agentix/session/whatsapp/
)

On first run a QR code is printed to stdout — scan it with WhatsApp to authenticate. The session is saved to auth_dir and reused on subsequent runs.

Key parameters

All parameters are keyword-only. All default to None and resolve through an environment variable fallback before settling on a built-in default.

Parameter	Default	Env var override	Description
auth_dir	<cwd>/.agentix/session/whatsapp/	WHATSAPP_AUTH_DIR	QR session storage directory
bridge_port	auto (free port)	WHATSAPP_BRIDGE_PORT	Port for the internal Node.js bridge
connect_timeout	120.0	WHATSAPP_CONNECT_TIMEOUT	Seconds to wait for QR scan / reconnect
mode	"self-chat"	WHATSAPP_MODE	"self-chat" or "bot"
allowed_users	None	WHATSAPP_ALLOWED_USERS	Restrict incoming messages to these numbers (mode="bot" requires this)
attachment_dir	<cwd>/media/whatsapp/	WHATSAPP_ATTACHMENT_DIR	Directory for received attachments
max_attachment_size	10 MB	WHATSAPP_MAX_ATTACHMENT_SIZE	Maximum attachment size in MB
skip_attachments	False	WHATSAPP_SKIP_ATTACHMENTS	Ignore all attachments

mode="bot" raises ConfigurationError at construction time if allowed_users is not provided.

Custom auth directory

Override auth_dir when you need a specific storage path:

gateway.add_channel(
    WhatsAppBaileysAdapter(
        auth_dir="/data/whatsapp-session",
    )
)

YAML config

channels:
  whatsapp_baileys:
    type: whatsapp_baileys
    mode: "bot"
    allowed_users:
      - "15551234567"
      - "15559876543"

Re-pairing

If the session breaks — phone reset, manual unlink from WhatsApp's Linked Devices, or a WhatsApp protocol update — you will see connection errors in the gateway logs. Delete the session directory and restart the gateway:

rm -rf .agentix/session/whatsapp/   # or your custom auth_dir
# restart the gateway — a fresh QR code will be printed

Scan the new QR code and the session is re-established. The gateway handles transient disconnections (network blips, phone going briefly offline) automatically with built-in reconnection logic — manual re-pairing is only needed when the session itself is invalidated.

---

The adapter can also be enabled/disabled without changing code by setting the WHATSAPP_ENABLED=true environment variable. When not set (or set to any other value) setup() is a no-op and the adapter does nothing.