WhatsApp Channel
The WhatsApp adapter connects a personal WhatsApp account to a Cortask workspace using the Baileys library, which interfaces with WhatsApp Web's multi-device protocol. There is no official WhatsApp Business API involved -- this works by linking an additional device to your WhatsApp account.
QR Code Authentication
Before starting the channel, you must authenticate by scanning a QR code:
- In the Cortask UI, go to your workspace's channel settings and add a WhatsApp channel.
- Click the button to generate a QR code. A QR code image will appear.
- Open WhatsApp on your phone, go to Linked Devices, and scan the QR code.
- Once authenticated, credentials are persisted to
~/.cortask/whatsapp-auth/so you do not need to re-scan on restart.
The QR code has a 60-second timeout. If it expires, generate a new one.
To log out and clear stored credentials, use the logout action in the UI. This removes the auth state directory entirely.
Trusted Contacts
WhatsApp uses a trusted contacts list for access control. Each contact has a phone number, an optional display name, and a permission level:
| Permission | Behavior |
|---|---|
read | Messages are acknowledged but the contact receives a "read-only access" reply instead of an agent response. |
write | Messages are forwarded to the agent and responses are sent back normally. |
admin | Same as write (reserved for future administrative capabilities). |
If the trusted contacts list is configured, any message from an unknown number is silently ignored.
A legacy allowedUsers list is also supported as a fallback, matching phone numbers with flexible normalization (with or without + prefix, spaces, etc.). Trusted contacts take priority when both are configured.
Starting and Stopping
- Start: Requires a valid auth state (QR previously scanned). The adapter opens a WebSocket connection to WhatsApp's servers and begins receiving messages. Automatic reconnection with exponential backoff handles temporary disconnections (up to 10 attempts, max 5-minute delay).
- Stop: The socket is closed and the session is logged out from WhatsApp's servers.
Terminal disconnection reasons (logged out, forbidden, multi-device mismatch) stop reconnection and require re-authentication.
Status Tracking
The adapter tracks connection state internally. While processing a message, it sends a "composing" (typing) presence indicator to the chat and clears it ("paused") when the response is sent. This gives the user visual feedback that the agent is working.
Limitations
- Text only: Only text messages and extended text messages are processed. Media, location, contacts, and other message types are ignored.
- Status broadcasts: Messages from the
status@broadcastJID are always ignored. - Own messages: Messages sent by the authenticated account itself (
fromMe) are ignored to prevent loops. - Single account: One WhatsApp adapter instance connects to one WhatsApp account.
- No message length limit enforced: WhatsApp does not have the same strict character limit as Telegram or Discord, but very long messages may be truncated by the client.