WhatsApp Channel for Chatons

A channel extension that bridges WhatsApp chats as Chatons conversations. Connect via QR code scanning, automatically sync messages, and use Chatons AI to reply to WhatsApp messages.

Features

• QR Code Connection: Scan a QR code with your WhatsApp to securely connect
• Message Polling: Continuously polls WhatsApp for new messages (configurable)
• Automatic Reply Mirror: Sends Chatons AI responses back to WhatsApp
• Chat Mapping: Maps WhatsApp chats to Chatons conversations automatically
• Media Support: Handles media files (photos, videos, documents, audio)
• Contact Filtering: Whitelist specific phone numbers to limit which chats are processed
• Background Service: Runs polling and mirroring even when UI is not visible
• Model Selection: Choose which AI model to use for new conversations

Installation

1. Clone the repository into your Chatons extensions directory:

cd ~/.chaton/extensions
git clone https://github.com/thibautrey/chatons-channel-whatsapp.git @thibautrey/chatons-channel-whatsapp

2. Restart Chatons

3. Go to Channels > WhatsApp to start using the extension

Configuration

QR Code Connection

1. Click "Generate QR Code" in the WhatsApp Channel UI
2. Scan the displayed QR code with your WhatsApp phone
3. The connection will establish automatically when confirmed

Settings

• Poll limit: Number of messages to fetch per polling cycle (1-100, default: 10)
• Allowed phone numbers (optional): Comma-separated list to whitelist specific contacts
• Mirror replies: Enable/disable automatic sending of Chatons responses to WhatsApp
• Handle media: Enable/disable downloading of photos, videos, and documents
• Model: Choose the AI model for new conversations

Phone Number Whitelist

Leave empty to allow all contacts, or specify comma-separated phone numbers (with or without + prefix):

+1234567890, +0987654321
1234567890, 0987654321

How It Works

Inbound Flow

1. WhatsApp messages are polled every 5 seconds
2. Each chat is automatically mapped to a Chatons conversation
3. The message is ingested and processed by the selected AI model
4. If a synchronous reply is available, it's immediately sent back to WhatsApp

Outbound Flow

1. Every 4 seconds, the extension checks for new AI responses
2. Any new assistant messages are automatically sent to the original WhatsApp chat
3. Messages are tracked to avoid duplicates

Background Service

• Polling continues even when the UI tab is closed
• Outbound mirroring runs in the background
• Keepalive timer ensures services resume if interrupted

Technical Details

State Management

All configuration and state is persisted to Chatons' storage:

• whatsapp.config: Connection settings and status
• whatsapp.mappings: Chat to conversation mappings
• whatsapp.lastUpdates: Recent activity log
• whatsapp.outboundMirrorState: Tracking of sent messages

Message Deduplication

• Uses message IDs and timestamps as idempotency keys
• Tracks which assistant messages have been sent to avoid duplicates
• Automatically recreates stale conversation mappings

Error Handling

• Graceful polling failure handling
• Automatic connection recovery via keepalive timer
• Detailed error notifications to user

Backend Integration

This extension uses a QR-code based connection approach similar to WhatsApp Web. In production, it should integrate with:

• whatsapp-web.js: A Node.js library that interfaces with WhatsApp Web
• Backend API: A service that manages WhatsApp Web.js instances and message polling

The current implementation includes mock functions that can be connected to a backend:

• initializeWhatsAppSession(): Generate QR code
• pollOnce(): Fetch new messages
• sendWhatsAppMessage(): Send message to WhatsApp

Security Considerations

• Session data (including phone number) is stored locally in Chatons' encrypted storage
• QR codes are session-based and expire after connection
• No credentials or API keys are stored
• Messages are only sent to whitelisted contacts (if configured)

Limitations

• Currently simulates connection (needs backend integration)
• Media downloading is prepared but needs backend implementation
• Requires stable internet connection for polling to work
• QR code changes with each reconnection for security

Contributing

Please open an issue or pull request to suggest improvements.

License

MIT