# 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)