WhatsApp Setup

The WhatsApp channel adapter connects your AI bots to WhatsApp with full end-to-end encryption. Unlike most WhatsApp integrations, this runs entirely in your browser -- no external bridge, no cloud service, no third-party server.

How It Works

The adapter implements the WhatsApp Web protocol natively in JavaScript:

1. QR Code Pairing -- AISCouncil generates a QR code. You scan it with your phone's WhatsApp app to link the browser as a companion device.
2. Noise XX Handshake -- An encrypted channel is established using X25519 key exchange (the same protocol WhatsApp uses).
3. Signal Double Ratchet -- Each message uses forward-secret keys via the Signal Protocol's Double Ratchet algorithm. Compromising one message key does not reveal past or future messages.
4. Message Routing -- Incoming WhatsApp messages are decrypted in the browser and routed to the assigned bot. The bot's response is encrypted and sent back.

Setup Steps

1. Open Settings > Connectors
2. Click Add Account and select WhatsApp
3. A QR code appears in the dialog
4. Open WhatsApp on your phone > Linked Devices > Link a Device
5. Scan the QR code with your phone
6. Wait for the connection to establish (status changes to "connected")
7. Optionally assign specific bots to this account

info

Your phone must be connected to the internet during the initial pairing. After pairing, the browser maintains its own session and can operate independently.

Encryption Details

Component	Implementation
Key Exchange	Noise XX protocol with X25519 ephemeral keys
Message Encryption	Signal Double Ratchet (AES-256-CBC + HMAC-SHA256)
Identity Keys	Curve25519 identity keypairs generated locally
Prekeys	30 prekeys generated at pairing, refilled when 5 remain
Max Skip	Up to 256 skipped message keys stored per chain
Message Format	Protobuf codec (236-token WABinary dictionary)

All cryptographic operations run in the browser using the Web Crypto API. Private keys never leave your device.

Connection Modes

The adapter supports two connection modes:

• Direct WebSocket -- Connects directly to WhatsApp's servers. Fastest, but may be blocked by corporate firewalls or restrictive networks.
• Relay Proxy -- Falls back to api.aiscouncil.net/v1/ws/whatsapp as a WebSocket relay. The relay forwards encrypted packets without decrypting them (it does not have your keys).

The adapter tries direct WebSocket first and automatically falls back to the relay if the connection fails.

Limitations

• One WhatsApp account per social account entry (you can add multiple WhatsApp accounts as separate social accounts)
• The browser tab must remain open for the bot to receive and respond to messages
• Group messages are received but responses are sent only to the sender (not the group) by default
• Media messages (images, voice, documents) are received as notifications but not processed by the bot

Troubleshooting

QR code expired: QR codes expire after 60 seconds. Click "Refresh" to generate a new one.

Connection drops frequently: Check your network. The adapter reconnects automatically, but frequent drops may indicate a firewall blocking WebSocket connections. Try the relay proxy mode.

"Linked device removed" error: Your phone may have unlinked the browser session. Re-scan the QR code to re-pair.