12871128e1
When user selects "dedicated bot number" mode (selfChatMode=false), skip the dmPolicy question and default to allowlist. Prompt for allowed phone numbers immediately. This is simpler and safer than pairing mode, which sends codes to whoever messages the bot. Users who want pairing or open mode can edit lettabot.yaml manually. Also updates docs to reflect the new defaults. Written by Cameron ◯ Letta Code "Simplicity is the ultimate sophistication." - Leonardo da Vinci
224 lines
6.5 KiB
Markdown
224 lines
6.5 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 `lettabot.yaml` or set environment variables:
|
|
|
|
```yaml
|
|
# lettabot.yaml
|
|
channels:
|
|
whatsapp:
|
|
enabled: true
|
|
selfChat: true # IMPORTANT: See below
|
|
```
|
|
|
|
Or via environment variables:
|
|
|
|
```bash
|
|
# WhatsApp Configuration
|
|
WHATSAPP_ENABLED=true
|
|
WHATSAPP_SELF_CHAT_MODE=true # CRITICAL - see below
|
|
```
|
|
|
|
**Note:** For personal numbers (`selfChat: true`), `dmPolicy` is ignored - only you can message via "Message Yourself". For dedicated bot numbers, onboarding defaults to `allowlist`.
|
|
|
|
### Self-Chat Mode (Critical Safety Setting)
|
|
|
|
**`selfChatMode: true`** (default, recommended for personal numbers):
|
|
- Bot ONLY responds to "Message Yourself" chat
|
|
- Bot will NOT message your contacts
|
|
- Safe to use with your personal WhatsApp number
|
|
|
|
**`selfChatMode: false`** (for dedicated bot numbers):
|
|
- Bot responds to ALL incoming messages
|
|
- Use ONLY with a dedicated phone number
|
|
- Risk of bot messaging your contacts if misconfigured
|
|
|
|
> **Warning:** If using your personal WhatsApp number, ALWAYS keep `selfChatMode: true` to prevent the bot from accidentally messaging your contacts.
|
|
|
|
## 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"
|
|
- **Use `selfChatMode: true`** to prevent bot from messaging your contacts
|
|
|
|
### 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
|
|
|
|
## Media Support
|
|
|
|
LettaBot supports receiving images, documents, and voice messages:
|
|
|
|
- **Images**: Downloaded and shown to the agent (agent can view using Read tool)
|
|
- **Voice messages**: Automatically transcribed via OpenAI Whisper
|
|
- **Documents**: Downloaded with metadata shown to agent
|
|
|
|
Configure attachment handling in `lettabot.yaml`:
|
|
|
|
```yaml
|
|
attachments:
|
|
maxMB: 20 # Max file size to download (default: 20MB)
|
|
maxAgeDays: 14 # Auto-delete after N days (default: 14)
|
|
```
|
|
|
|
Attachments are stored in `/tmp/lettabot/attachments/` by default.
|
|
|
|
## 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. Check `selfChatMode` setting - if `true`, only "Message Yourself" works
|
|
2. Make sure the sender's number is allowed by `dmPolicy` setting
|
|
3. If `dmPolicy: allowlist`, check `allowedUsers` list
|
|
4. 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)
|
|
- [Discord Setup](./discord-setup.md)
|
|
- [Signal Setup](./signal-setup.md)
|