455 lines
14 KiB
Markdown
455 lines
14 KiB
Markdown
# LettaBot
|
|
|
|
Your personal AI assistant that remembers everything across **Telegram, Slack, Discord, WhatsApp, and Signal** — plus Bluesky Jetstream feed ingestion. Powered by the [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk).
|
|
|
|
<img width="750" alt="lettabot-preview" src="assets/preview.jpg" />
|
|
|
|
[](https://railway.com/deploy/lettabot?utm_medium=integration&utm_source=template&utm_campaign=generic)
|
|
|
|
[](https://discord.gg/letta)
|
|
|
|
> [!IMPORTANT]
|
|
> *"Help! I need help with my LettaBot!"* 👋
|
|
>
|
|
> Need help? The fastest way to get help with LettaBot is to ask an AI coding agent, like [Letta Code](https://docs.letta.com/letta-code)! The LettaBot codebase is meant to be hackable, meaning a (good) agent should be able to dive right in and help you out.
|
|
|
|
## Features
|
|
|
|
- **Multi-Channel** - Chat seamlessly across Telegram, Slack, Discord, WhatsApp, and Signal
|
|
- **Feed Ingestion** - Read-only Bluesky Jetstream stream for selected DID(s)
|
|
- **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
|
|
- **Voice Messages** - Automatic transcription via OpenAI Whisper
|
|
- **Heartbeat** - Periodic check-ins where the agent reviews tasks
|
|
- **Scheduling** - Agent can create one-off reminders and recurring tasks
|
|
- **Streaming Responses** - Real-time message updates as the agent thinks
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 20+
|
|
- A Letta API key from [app.letta.com](https://app.letta.com) (or a running [Letta Docker server](https://docs.letta.com/guides/docker/))
|
|
- A Telegram bot token from [@BotFather](https://t.me/BotFather)
|
|
- Optional: a ChatGPT subscription account you want to use for model credits
|
|
|
|
### Install
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/letta-ai/lettabot.git
|
|
cd lettabot
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build and link the CLI globally
|
|
npm run build
|
|
npm link
|
|
```
|
|
|
|
### Update
|
|
|
|
```bash
|
|
# Pull latest changes
|
|
git pull origin main
|
|
|
|
# Reinstall dependencies and rebuild
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
#### Optional: Run a Letta Docker server
|
|
You can use `lettabot` with a Docker server with:
|
|
```
|
|
docker run \
|
|
-v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
|
|
-p 8283:8283 \
|
|
-e OPENAI_API_KEY="your_openai_api_key" \
|
|
letta/letta:latest
|
|
```
|
|
See the [documentation](https://docs.letta.com/guides/docker/) for more details on running with Docker.
|
|
|
|
### Setup
|
|
|
|
**Option 1: AI-Assisted Setup (Recommended)**
|
|
|
|
Paste this into Letta Code, Claude Code, Cursor, or any AI coding assistant:
|
|
|
|
```
|
|
Clone https://github.com/letta-ai/lettabot, read the SKILL.md
|
|
for setup instructions, and help me configure Telegram.
|
|
```
|
|
|
|
You'll need:
|
|
- A Letta API key from [app.letta.com](https://app.letta.com) (or a [Letta Docker server](https://docs.letta.com/guides/docker/))
|
|
- A Telegram bot token from [@BotFather](https://t.me/BotFather)
|
|
|
|
The AI will handle cloning, installing, and configuration autonomously.
|
|
|
|
**Option 2: Interactive Wizard**
|
|
|
|
For manual step-by-step setup:
|
|
|
|
```bash
|
|
git clone https://github.com/letta-ai/lettabot.git
|
|
cd lettabot
|
|
npm install && npm run build && npm link
|
|
lettabot onboard
|
|
```
|
|
|
|
Prefer to use your ChatGPT subscription instead of another API key? After onboarding (or anytime), run:
|
|
|
|
```bash
|
|
lettabot connect chatgpt
|
|
```
|
|
|
|
This opens a browser flow and enables connected subscription handles in the model picker.
|
|
|
|
### Run
|
|
|
|
```bash
|
|
lettabot server
|
|
```
|
|
|
|
That's it! Message your bot on Telegram.
|
|
|
|
> **Note:** For detailed environment variable reference and multi-channel setup, see [SKILL.md](./SKILL.md)
|
|
|
|
## Voice
|
|
|
|
LettaBot can transcribe incoming voice messages (via OpenAI Whisper or Mistral Voxtral) and reply with voice memos (via ElevenLabs or OpenAI TTS). Voice notes render as native bubbles on Telegram and WhatsApp.
|
|
|
|
**Supported channels:** Telegram, WhatsApp, Signal, Slack, Discord
|
|
|
|
See [docs/voice.md](./docs/voice.md) for full setup, configuration, and troubleshooting.
|
|
|
|
## Skills
|
|
LettaBot is compatible with [skills.sh](https://skills.sh) and [Clawdhub](https://clawdhub.com/).
|
|
|
|
```bash
|
|
# from Clawdhub
|
|
npx molthub@latest install sonoscli
|
|
|
|
# from skills.sh
|
|
npm run skills:add supabase/agent-skills
|
|
|
|
# connect to LettaBot
|
|
lettabot skills
|
|
|
|
◆ Enable skills (space=toggle, enter=confirm):
|
|
│ ◻ ── ClawdHub Skills ── (~/clawd/skills)
|
|
│ ◻ 🦞 sonoscli
|
|
│ ◻ ── Vercel Skills ── (~/.agents/skills)
|
|
│ ◻ 🔼 supabase/agent-skills
|
|
│ ◻ ── Built-in Skills ──
|
|
│ ◻ 📦 1password
|
|
│ ◻ ...
|
|
|
|
# View LettaBot skills
|
|
lettabot skills status
|
|
```
|
|
|
|
### Home Assistant
|
|
|
|
Control your smart home with LettaBot:
|
|
|
|
```bash
|
|
# 1. Install the skill from ClawdHub
|
|
npx clawdhub@latest install homeassistant
|
|
|
|
# 2. Enable the skill
|
|
lettabot skills sync
|
|
# Select "homeassistant" from the list
|
|
|
|
# 3. Configure credentials (see skill docs for details)
|
|
# You'll need: HA URL + Long-Lived Access Token
|
|
```
|
|
|
|
Then ask your bot things like:
|
|
- "Turn off the living room lights"
|
|
- "What's the temperature in the bedroom?"
|
|
- "Set the thermostat to 72"
|
|
|
|
## CLI Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `lettabot onboard` | Interactive setup wizard |
|
|
| `lettabot connect` | Connect model providers (for example, `chatgpt`) |
|
|
| `lettabot server` | Start the bot server |
|
|
| `lettabot configure` | View and edit configuration |
|
|
| `lettabot skills status` | Show enabled and available skills |
|
|
| `lettabot destroy` | Delete all local data and start fresh |
|
|
| `lettabot help` | Show help |
|
|
|
|
## Channel Setup
|
|
|
|
By default, LettaBot uses a **single agent with a single shared conversation** across all channels:
|
|
|
|
```
|
|
Telegram ──┐
|
|
Slack ─────┤
|
|
Discord ───┼──→ ONE AGENT ──→ ONE CONVERSATION
|
|
WhatsApp ──┤ (memory) (chat history)
|
|
Signal ────┘
|
|
```
|
|
|
|
- Start a conversation on Telegram
|
|
- Continue it on Slack
|
|
- Pick it up on WhatsApp
|
|
- The agent remembers everything!
|
|
|
|
You can also enable **per-channel conversations** (one conversation per channel adapter, not per chat/user):
|
|
|
|
```
|
|
Telegram ──→ CONVERSATION (telegram)
|
|
Slack ─────→ CONVERSATION (slack)
|
|
Discord ───→ CONVERSATION (discord)
|
|
WhatsApp ──→ CONVERSATION (whatsapp)
|
|
Signal ────→ CONVERSATION (signal)
|
|
(shared agent memory across channels)
|
|
```
|
|
|
|
Configure in `lettabot.yaml`:
|
|
|
|
```yaml
|
|
conversations:
|
|
mode: shared # default: one conversation across all channels
|
|
heartbeat: last-active # "dedicated" | "last-active" | "<channel>"
|
|
```
|
|
|
|
For multi-agent configs, the same block lives under each agent:
|
|
|
|
```yaml
|
|
agents:
|
|
- name: MyAgent
|
|
conversations:
|
|
mode: per-channel
|
|
heartbeat: dedicated
|
|
```
|
|
|
|
| Channel | Guide | Requirements |
|
|
|---------|-------|--------------|
|
|
| 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 |
|
|
| Bluesky (read-only) | [Setup Guide](docs/bluesky-setup.md) | Jetstream WebSocket + DID filter |
|
|
|
|
At least one channel is required. Telegram is the easiest to start with.
|
|
|
|
### Group Settings (Optional)
|
|
|
|
Configure group batching and per-group response modes in `lettabot.yaml`:
|
|
|
|
```yaml
|
|
channels:
|
|
slack:
|
|
groupDebounceSec: 5
|
|
mentionPatterns: ["@mybot", "hey bot"]
|
|
groups:
|
|
"*": { mode: mention-only } # default for all groups
|
|
"C0987654321": { mode: listen } # observe, only reply on mention
|
|
"C0123456789": { mode: open, allowedUsers: ["U123"] }
|
|
```
|
|
|
|
Group modes:
|
|
- `open`: process + respond to all group messages
|
|
- `listen`: process for memory, but auto-replies only on mention
|
|
- `mention-only`: only process when mentioned
|
|
- `disabled`: ignore all group messages
|
|
|
|
Notes:
|
|
- `instantGroups` still bypasses batching (legacy).
|
|
- `listeningGroups` and `groups.<id>.requireMention` are deprecated; use `groups.<id>.mode`.
|
|
|
|
See `SKILL.md` for the full environment variable list and examples.
|
|
|
|
## Bot Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/start` | Welcome message and help |
|
|
| `/status` | Show current session info |
|
|
| `/heartbeat` | Manually trigger a heartbeat check-in |
|
|
|
|
## Background Tasks (Heartbeats & Cron)
|
|
|
|
Heartbeats always run in **Silent Mode**. Cron jobs are **silent by default**, but can auto-deliver responses when created with `--deliver channel:chatId`.
|
|
|
|
Silent Mode means the agent's text responses are NOT automatically sent to users during background tasks. This is intentional: the agent decides when something is worth interrupting you for.
|
|
|
|
To send messages during silent mode, the agent must explicitly use the CLI:
|
|
|
|
```bash
|
|
lettabot-message send --text "Hey, I found something interesting!"
|
|
```
|
|
|
|
The agent sees a clear `[SILENT MODE]` banner when triggered by heartbeats/cron, along with instructions on how to use the CLI.
|
|
|
|
**Requirements for background messaging (silent mode):**
|
|
- The **Bash tool must be enabled** for the agent to run the CLI
|
|
- A user must have messaged the bot at least once (to establish a delivery target) unless you provide an explicit target
|
|
|
|
If your agent isn't sending messages during heartbeats, check the [ADE](https://app.letta.com) to see what the agent is doing and whether it's attempting to use `lettabot-message`.
|
|
|
|
## Agent CLI Tools
|
|
|
|
LettaBot includes small CLIs the agent can invoke via Bash (or you can run directly):
|
|
|
|
```bash
|
|
lettabot-message send --text "Hello from a background task"
|
|
lettabot-react add --emoji :eyes: --channel discord --chat 123 --message 456
|
|
lettabot-history fetch --limit 25 --channel discord --chat 123456789
|
|
```
|
|
|
|
See [CLI Tools](docs/cli-tools.md) for details and limitations.
|
|
|
|
## Connect to Letta Code
|
|
Any LettaBot agent can also be directly chatted with through [Letta Code](https://github.com/letta-ai/letta-code). Use the `/status` command to find your `agent_id`, and run:
|
|
```sh
|
|
letta --agent <agent_id>
|
|
```
|
|
|
|
## OpenAI-Compatible API
|
|
|
|
LettaBot exposes `/v1/chat/completions` and `/v1/models` endpoints, so you can use any OpenAI SDK or compatible frontend (like [Open WebUI](https://github.com/open-webui/open-webui)) to chat with your agents:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8080/v1/chat/completions \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer YOUR_API_KEY" \
|
|
-d '{"model": "lettabot", "messages": [{"role": "user", "content": "Hello!"}]}'
|
|
```
|
|
|
|
Supports sync and streaming responses. See the [full documentation](docs/openai-compat.md) for Python/Node SDK examples and details.
|
|
|
|
## Security
|
|
|
|
### Network Architecture
|
|
|
|
**LettaBot uses outbound connections only** - no public URL or gateway required:
|
|
|
|
| Channel | Connection Type | Exposed Ports |
|
|
|---------|-----------------|---------------|
|
|
| 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 |
|
|
|
|
### Tool Execution
|
|
|
|
By default, the agent is restricted to **read-only** operations:
|
|
- `Read`, `Glob`, `Grep` - File exploration
|
|
- `web_search` - Internet queries
|
|
- `conversation_search` - Search past messages
|
|
|
|
### Access Control
|
|
|
|
LettaBot supports pairing-based access control. When `TELEGRAM_DM_POLICY=pairing`:
|
|
1. Unauthorized users get a pairing code
|
|
2. Approve codes via:
|
|
- **Web portal** at `https://your-host/portal` (recommended for cloud deploys)
|
|
- **CLI**: `lettabot pairing approve telegram <CODE>`
|
|
- **API**: `POST /api/v1/pairing/telegram/approve`
|
|
3. Approved users can then chat with the bot
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run in development mode (auto-reload)
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Start production server
|
|
lettabot server
|
|
```
|
|
|
|
## Releases
|
|
|
|
Releases are automated via GitHub Actions. When a version tag is pushed, the workflow builds, tests, generates release notes from merged PRs, and creates a GitHub Release.
|
|
|
|
```bash
|
|
# Create a release
|
|
git tag v0.2.0
|
|
git push origin v0.2.0
|
|
|
|
# Create a pre-release (alpha/beta/rc are auto-detected)
|
|
git tag v0.2.0-alpha.1
|
|
git push origin v0.2.0-alpha.1
|
|
```
|
|
|
|
See all releases: [GitHub Releases](https://github.com/letta-ai/lettabot/releases)
|
|
|
|
## Troubleshooting
|
|
|
|
### WhatsApp
|
|
|
|
**Cannot find package 'keyv'**
|
|
```
|
|
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'keyv'
|
|
```
|
|
Clean reinstall fixes this:
|
|
```bash
|
|
rm -rf node_modules package-lock.json && npm install
|
|
```
|
|
|
|
**Session errors / "Bad MAC" messages**
|
|
These are normal Signal Protocol renegotiation messages. They're noisy but harmless.
|
|
|
|
**Messages going to wrong chat**
|
|
Clear the session and re-link:
|
|
```bash
|
|
rm -rf ./data/whatsapp-session
|
|
lettabot server # Scan QR again
|
|
```
|
|
|
|
### Signal
|
|
|
|
**Port 8090 already in use**
|
|
```bash
|
|
SIGNAL_HTTP_PORT=8091
|
|
```
|
|
|
|
### General
|
|
|
|
**Agent not responding**
|
|
Delete the agent store to create a fresh agent:
|
|
```bash
|
|
lettabot destroy
|
|
```
|
|
|
|
**Heartbeat/cron messages not reaching my chat**
|
|
Heartbeats and cron jobs run in "Silent Mode" - the agent's text output is private and not auto-delivered. To send messages during background tasks, the agent must run:
|
|
```bash
|
|
lettabot-message send --text "Your message here"
|
|
```
|
|
Check the [ADE](https://app.letta.com) to see if your agent is attempting to use this command. Common issues:
|
|
- Bash tool not enabled (agent can't run CLI commands)
|
|
- Agent doesn't understand it needs to use the CLI
|
|
- No delivery target set (user never messaged the bot first)
|
|
|
|
## Documentation
|
|
|
|
- [Getting Started](docs/getting-started.md)
|
|
- [Docker Server Setup](docs/selfhosted-setup.md) - Run with your own Letta server
|
|
- [Configuration Reference](docs/configuration.md)
|
|
- [OpenAI-Compatible API](docs/openai-compat.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)
|
|
|
|
## Acknowledgement
|
|
Some skills were adapted from [Moltbot](https://github.com/moltbot/moltbot).
|
|
|
|
## License
|
|
|
|
Apache-2.0
|