22770e6e88
Co-authored-by: Cameron Pfiffer <cameron@pfiffer.org> Co-authored-by: Caren Thomas <carenthomas@gmail.com> Co-authored-by: Charles Packer <packercharles@gmail.com> Co-authored-by: Sarah Wooders <sarahwooders@gmail.com>
183 lines
5.0 KiB
Markdown
183 lines
5.0 KiB
Markdown
# WhatsApp Setup for LettaBot
|
|
|
|
This guide walks you through setting up WhatsApp as a channel for LettaBot.
|
|
|
|
## Overview
|
|
|
|
LettaBot connects to WhatsApp using **Baileys**, which uses the WhatsApp Web protocol. This means:
|
|
- Uses your personal WhatsApp account (or a dedicated number)
|
|
- No WhatsApp Business API required
|
|
- Free to use
|
|
- Requires QR code scan on first setup
|
|
|
|
## Prerequisites
|
|
|
|
- A phone with WhatsApp installed
|
|
- LettaBot installed and configured with at least `LETTA_API_KEY`
|
|
|
|
## Step 1: Enable WhatsApp in Configuration
|
|
|
|
Add to your `.env` file:
|
|
|
|
```bash
|
|
# WhatsApp Configuration
|
|
WHATSAPP_ENABLED=true
|
|
|
|
# Optional: Custom session storage path (default: ./data/whatsapp-session)
|
|
# WHATSAPP_SESSION_PATH=./data/whatsapp-session
|
|
|
|
# Optional: Restrict to specific phone numbers
|
|
# WHATSAPP_ALLOWED_USERS=+15551234567,+15559876543
|
|
```
|
|
|
|
## Step 2: Start LettaBot
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
You'll see output like:
|
|
```
|
|
Registered channel: WhatsApp
|
|
[WhatsApp] Scan the QR code above to login
|
|
```
|
|
|
|
A QR code will be displayed in your terminal.
|
|
|
|
## Step 3: Scan the QR Code
|
|
|
|
1. Open WhatsApp on your phone
|
|
2. Go to **Settings** → **Linked Devices**
|
|
3. Tap **"Link a Device"**
|
|
4. Scan the QR code displayed in your terminal
|
|
|
|
Once connected, you'll see:
|
|
```
|
|
[WhatsApp] Connected!
|
|
```
|
|
|
|
## Step 4: Test the Integration
|
|
|
|
1. From another phone (or WhatsApp Web with a different account), send a message to the number you just linked
|
|
2. The bot should respond
|
|
|
|
Or test with yourself:
|
|
1. Open a note-to-self chat (message yourself)
|
|
2. Send a test message
|
|
|
|
## Session Persistence
|
|
|
|
After the first QR scan, your session is saved to disk (default: `./data/whatsapp-session/`).
|
|
|
|
On subsequent restarts:
|
|
- No QR scan needed
|
|
- Bot reconnects automatically
|
|
- If session expires, a new QR code will be shown
|
|
|
|
## Restricting Access
|
|
|
|
To restrict which phone numbers can interact with the bot:
|
|
|
|
```bash
|
|
# Include country code with + prefix
|
|
WHATSAPP_ALLOWED_USERS=+15551234567,+15559876543
|
|
```
|
|
|
|
**Note**: Only DMs are restricted. Group messages may still be received (but not responded to unless the sender is allowed).
|
|
|
|
## Cross-Channel Memory
|
|
|
|
Since LettaBot uses a single agent across all channels:
|
|
- Messages from WhatsApp continue the same conversation as Telegram/Slack
|
|
- The agent remembers context from all channels
|
|
- Start a conversation on Telegram, continue it on WhatsApp
|
|
|
|
## Important Limitations
|
|
|
|
### Message Editing
|
|
WhatsApp doesn't support editing messages. When the bot streams a long response, it will send the full message at once rather than updating incrementally.
|
|
|
|
### Rate Limits
|
|
WhatsApp has strict rate limits to prevent spam:
|
|
- Don't send too many messages too quickly
|
|
- Avoid automated bulk messaging
|
|
- Risk of account ban if abused
|
|
|
|
### Personal Account
|
|
This uses your personal WhatsApp account:
|
|
- Messages appear as coming from your number
|
|
- Consider using a dedicated phone number for the bot
|
|
- Your contacts will see the bot as "you"
|
|
|
|
### Multi-Device Limitations
|
|
- WhatsApp allows up to 4 linked devices
|
|
- The bot counts as one linked device
|
|
- If you unlink the bot, you'll need to scan the QR code again
|
|
|
|
## Running in Production
|
|
|
|
For production deployments:
|
|
|
|
1. **Use a dedicated phone number** - Don't use your personal WhatsApp
|
|
2. **Persistent storage** - Make sure `WHATSAPP_SESSION_PATH` points to persistent storage
|
|
3. **Monitor reconnections** - The bot auto-reconnects, but check logs for issues
|
|
4. **Backup session** - Back up the session folder to avoid re-scanning QR codes
|
|
|
|
## Troubleshooting
|
|
|
|
### QR Code Not Showing
|
|
|
|
If no QR code appears:
|
|
- Check that `WHATSAPP_ENABLED=true` is set
|
|
- Look for error messages in the console
|
|
- Make sure you have a terminal that supports QR code display
|
|
|
|
### "Connection Closed" Errors
|
|
|
|
This usually means:
|
|
- WhatsApp Web session was logged out from your phone
|
|
- Network connectivity issues
|
|
- WhatsApp servers are temporarily unavailable
|
|
|
|
The bot will automatically try to reconnect.
|
|
|
|
### "Logged Out" State
|
|
|
|
If you see "logged out" in the logs:
|
|
1. Delete the session folder: `rm -rf ./data/whatsapp-session`
|
|
2. Restart LettaBot
|
|
3. Scan the new QR code
|
|
|
|
### Messages Not Being Received
|
|
|
|
1. Make sure the sender's number is in `WHATSAPP_ALLOWED_USERS` (if configured)
|
|
2. Check that the message is a text message (media not fully supported yet)
|
|
3. Look for errors in the console
|
|
|
|
### Bot Responding to Old Messages
|
|
|
|
On first connection, the bot might receive some historical messages. This is normal WhatsApp behavior. The bot will only respond to new messages going forward.
|
|
|
|
## Security Notes
|
|
|
|
- **Session files** contain authentication data - keep them secure
|
|
- Don't share your session folder
|
|
- Use `WHATSAPP_ALLOWED_USERS` to restrict who can interact with the bot
|
|
- Consider the privacy implications of using a personal number
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
data/
|
|
└── whatsapp-session/
|
|
├── creds.json # Authentication credentials
|
|
├── app-state-sync-* # App state
|
|
└── ... # Other session data
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [Slack Setup](./slack-setup.md)
|
|
- [Cron Jobs](./cron-setup.md)
|
|
- [Configuration Reference](./configuration.md)
|