diff --git a/README.md b/README.md index c2466a3..c44d278 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # LettaBot -Your personal AI assistant that remembers everything across **Telegram, Slack, WhatsApp, and Signal**. Powered by the [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk). +Your personal AI assistant that remembers everything across **Telegram, Slack, Discord, WhatsApp, and Signal**. Powered by the [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk). lettabot-preview ## Features -- **Multi-Channel** - Chat seamlessly across Telegram, Slack, WhatsApp, and Signal +- **Multi-Channel** - Chat seamlessly across Telegram, Slack, Discord, WhatsApp, and Signal - **Unified Memory** - Single agent remembers everything from all channels - **Persistent Memory** - Agent remembers conversations across sessions (days/weeks/months) - **Local Tool Execution** - Agent can read files, search code, run commands on your machine @@ -129,9 +129,10 @@ LettaBot uses a **single agent with a single conversation** across all channels: ``` Telegram ──┐ - ├──→ ONE AGENT ──→ ONE CONVERSATION -Slack ─────┤ (memory) (chat history) -WhatsApp ──┘ +Slack ─────┤ +Discord ───┼──→ ONE AGENT ──→ ONE CONVERSATION +WhatsApp ──┤ (memory) (chat history) +Signal ────┘ ``` - Start a conversation on Telegram @@ -143,6 +144,7 @@ WhatsApp ──┘ |---------|-------|--------------| | Telegram | [Setup Guide](docs/getting-started.md) | Bot token from @BotFather | | Slack | [Setup Guide](docs/slack-setup.md) | Slack app with Socket Mode | +| Discord | [Setup Guide](docs/discord-setup.md) | Discord bot + Message Content Intent | | WhatsApp | [Setup Guide](docs/whatsapp-setup.md) | Phone with WhatsApp | | Signal | [Setup Guide](docs/signal-setup.md) | signal-cli + phone number | @@ -172,6 +174,7 @@ letta --agent |---------|-----------------|---------------| | Telegram | Long-polling (outbound HTTP) | None | | Slack | Socket Mode (outbound WebSocket) | None | +| Discord | Gateway (outbound WebSocket) | None | | WhatsApp | Outbound WebSocket via Baileys | None | | Signal | Local daemon on 127.0.0.1 | None | @@ -235,6 +238,7 @@ lettabot destroy - [Getting Started](docs/getting-started.md) - [Slack Setup](docs/slack-setup.md) +- [Discord Setup](docs/discord-setup.md) - [WhatsApp Setup](docs/whatsapp-setup.md) - [Signal Setup](docs/signal-setup.md) diff --git a/docs/discord-setup.md b/docs/discord-setup.md new file mode 100644 index 0000000..6662cc7 --- /dev/null +++ b/docs/discord-setup.md @@ -0,0 +1,208 @@ +# Discord Setup for LettaBot + +This guide walks you through setting up Discord as a channel for LettaBot. + +## Overview + +LettaBot connects to Discord using a **Bot Application** with the Gateway API: +- No public URL required (uses WebSocket connection) +- Works behind firewalls +- Real-time bidirectional communication + +## Prerequisites + +- A Discord server where you have permission to add bots +- LettaBot installed and configured with at least `LETTA_API_KEY` + +## Step 1: Create a Discord Application + +1. Go to **https://discord.com/developers/applications** +2. Click **"New Application"** +3. Enter a name (e.g., `LettaBot`) +4. Click **"Create"** + +## Step 2: Create the Bot + +1. In the left sidebar, click **"Bot"** +2. Click **"Reset Token"** (or "Add Bot" if this is new) +3. **Copy the token** - this is your `DISCORD_BOT_TOKEN` + + > **Important**: You can only see this token once. If you lose it, you'll need to reset it. + +## Step 3: Enable Message Content Intent + +This is required for the bot to read message content. + +1. Still in the **"Bot"** section +2. Scroll down to **"Privileged Gateway Intents"** +3. Enable **"MESSAGE CONTENT INTENT"** +4. Click **"Save Changes"** + +## Step 4: Generate Invite URL + +1. In the left sidebar, go to **"OAuth2"** → **"URL Generator"** +2. Under **"Scopes"**, select: + - `bot` +3. Under **"Bot Permissions"**, select: + - `Send Messages` + - `Read Message History` + - `View Channels` +4. Copy the generated URL at the bottom + +Or use this URL template (replace `YOUR_CLIENT_ID`): +``` +https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=68608&scope=bot +``` + +> **Tip**: Your Client ID is in **"General Information"** or in the URL when viewing your app. + +## Step 5: Add Bot to Your Server + +1. Open the invite URL from Step 4 in your browser +2. Select the server you want to add the bot to +3. Click **"Authorize"** +4. Complete the CAPTCHA if prompted + +You should see `[Bot Name] has joined the server` in Discord. + +## Step 6: Configure LettaBot + +Run the onboarding wizard and select Discord: + +```bash +lettabot onboard +``` + +Or add directly to your `lettabot.yaml`: + +```yaml +channels: + discord: + enabled: true + token: "your-bot-token-here" + dmPolicy: pairing # or 'allowlist' or 'open' +``` + +## Step 7: Start LettaBot + +```bash +lettabot server +``` + +You should see: +``` +Registered channel: Discord +[Discord] Connecting... +[Discord] Bot logged in as YourBot#1234 +[Discord] DM policy: pairing +``` + +## Step 8: Test the Integration + +### In a Server Channel +1. Go to a text channel in your Discord server +2. Type `@YourBot hello!` +3. The bot should respond + +### Direct Message +1. Right-click on the bot in the server member list +2. Click **"Message"** +3. Send a message: `Hello!` +4. The bot should respond (may require pairing approval first) + +## Access Control + +LettaBot supports three DM policies for Discord: + +### Pairing (Recommended) +```yaml +dmPolicy: pairing +``` +- New users receive a pairing code +- Approve with: `lettabot pairing approve discord ` +- Most secure for personal use + +### Allowlist +```yaml +dmPolicy: allowlist +allowedUsers: + - "123456789012345678" # Discord user IDs +``` +- Only specified users can interact +- Find user IDs: Enable Developer Mode in Discord settings, then right-click a user → "Copy User ID" + +### Open +```yaml +dmPolicy: open +``` +- Anyone can message the bot +- Not recommended for personal bots + +## Adding Reactions + +LettaBot can react to messages using the `lettabot-react` CLI: + +```bash +# React to the most recent message +lettabot-react add --emoji ":eyes:" + +# React to a specific message +lettabot-react add --emoji ":thumbsup:" --channel discord --chat 123456789 --message 987654321 +``` + +## Troubleshooting + +### Bot shows as offline + +1. Make sure LettaBot is running (`lettabot server`) +2. Check for errors in the console +3. Verify your bot token is correct + +### Bot doesn't respond to messages + +1. **Check MESSAGE CONTENT INTENT** is enabled: + - Discord Developer Portal → Your App → Bot → Privileged Gateway Intents + - Toggle ON "MESSAGE CONTENT INTENT" + +2. **Check bot has permissions** in the channel: + - Server Settings → Roles → Your Bot's Role + - Or check channel-specific permissions + +3. **Check pairing status** if using pairing mode: + - New users need to be approved via `lettabot pairing list` + +### "0 Servers" in Developer Portal + +The bot hasn't been invited to any servers yet. Use the invite URL from Step 4. + +### Bot can't DM users + +Discord bots can only DM users who: +- Share a server with the bot, OR +- Have previously DM'd the bot + +This is a Discord limitation, not a LettaBot issue. + +### Rate limiting + +If the bot stops responding temporarily, it may be rate-limited by Discord. Wait a few minutes and try again. Avoid sending many messages in quick succession. + +## Security Notes + +- **Bot tokens** should be kept secret - never commit them to git +- Use `dmPolicy: pairing` or `allowlist` in production +- The bot can only see messages in channels it has access to +- DMs are only visible between the bot and that specific user + +## Cross-Channel Memory + +Since LettaBot uses a single agent across all channels: +- Messages you send on Discord continue the same conversation as Telegram/Slack +- The agent remembers context from all channels +- You can start a conversation on Telegram and continue it on Discord + +## Next Steps + +- [Slack Setup](./slack-setup.md) +- [WhatsApp Setup](./whatsapp-setup.md) +- [Signal Setup](./signal-setup.md)