Connections

A connection is a linked WhatsApp account. When you create a connection, WAHooks provisions a cloud-hosted WAHA session that maintains the WhatsApp Web connection on your behalf.

Architecture

Your App → WAHooks API → WAHA Worker Pod → WhatsApp

Each connection runs in its own isolated container (WAHA pod) in the WAHooks Kubernetes cluster. The pod handles:

• WhatsApp Web protocol (NOWEB engine)
• Message sending and receiving
• Event forwarding to the WAHooks API
• Session persistence (survives pod restarts)

Session lifecycle

1. Create (pending) — a WAHA pod is provisioned and a session is created
2. QR Scan (scan_qr) — you scan a QR code with WhatsApp to link the account
3. Connected (connected) — the session is active, messages flow in and out
4. Failed (failed) — the session lost connection (auto-recovered within 3 minutes)
5. Stopped (stopped) — you deleted the connection

Health monitoring

WAHooks polls WAHA sessions every 3 minutes:

• FAILED sessions are automatically reset and restarted
• STOPPED sessions that should be active are restarted
• Missing sessions (after pod restart) are auto-created with full config

One session per number

Each WhatsApp number can only be linked to one connection at a time. Creating a new connection for a number that's already linked elsewhere will unlink the existing session.

Chat IDs

WhatsApp uses specific ID formats:

Use the chats endpoint to discover chat IDs.