Connect Hermes to WhatsApp with Baileys

Hermes can connect to WhatsApp through a built-in Baileys bridge that emulates WhatsApp Web. It needs no Meta developer account or public webhook, but it is unofficial and carries account-restriction risk. For a business deployment, compare it with the official WhatsApp Business Cloud API before choosing.

Choose an operating mode

A dedicated bot number is the safer Baileys pattern: it isolates personal history, supports multiple approved users, and limits the impact of a bridge problem. Self-chat mode is convenient for private testing but ties the integration to a personal account.

Run hermes whatsapp, select the mode, and scan the terminal QR code from WhatsApp's Linked Devices screen. The encrypted session is stored under ~/.hermes/platforms/whatsapp/session and survives restarts. Protect that directory like a password.

Configure an explicit sender allowlist or use Hermes's DM pairing system. A private number can set unauthorized DM behavior to ignore so strangers do not receive pairing replies. Then start the gateway and monitor the bridge logs.

Safety checklist

Prefer a dedicated number instead of a personal account.
Keep use conversational; never send bulk or unsolicited messages.
Configure exact allowed users or a deliberate pairing policy.
Restrict the session directory to the account owner.
Persist the session volume when containerizing the gateway.
Keep Hermes updated for WhatsApp Web protocol changes.

Pitfalls

This bridge is not the official Business API and can break after protocol updates. QR codes expire quickly. A launch service may not inherit the shell PATH even when Node works interactively. Allow-all access exposes the agent to every sender. Session files contain device credentials and must never enter source control, backups shared with others, or screenshots.

Verification steps

Pair the intended WhatsApp account and restart the gateway.
Send one message from an allowed number and verify one response.
Test an unauthorized sender and confirm the chosen ignore or pairing behavior.
Restart the machine or service and confirm the session persists.
Inspect logs for redaction and repeated reconnect loops.

Read the official Baileys WhatsApp guide and compare the official Cloud API path before production use.