deb1c4532a
* feat: add POST /api/v1/chat endpoint for sending messages to agents Adds an HTTP endpoint that accepts a JSON message, sends it to the lettabot agent via sendToAgent(), and returns the agent's response. This enables external systems (e.g. server-side tools in other agents) to communicate with lettabot programmatically. - Add ChatRequest/ChatResponse types - Add AgentRouter interface extending MessageDeliverer with sendToAgent() - Implement AgentRouter on LettaGateway with agent-name routing - Add POST /api/v1/chat route with auth, validation, and JSON body parsing Written by Cameron ◯ Letta Code "The most profound technologies are those that disappear." -- Mark Weiser * feat: add SSE streaming support to /api/v1/chat endpoint When the client sends Accept: text/event-stream, the chat endpoint streams SDK messages as SSE events instead of waiting for the full response. Each event is a JSON StreamMsg (assistant, tool_call, tool_result, reasoning, result). The result event signals end-of-stream. - Export StreamMsg type from bot.ts - Add streamToAgent() to AgentSession interface and LettaBot - Wire streamToAgent() through LettaGateway with agent-name routing - Add SSE path in chat route (Accept header content negotiation) - Handle client disconnect mid-stream gracefully Written by Cameron ◯ Letta Code "Any sufficiently advanced technology is indistinguishable from magic." -- Arthur C. Clarke * test+docs: add chat endpoint tests and API documentation - 10 tests for POST /api/v1/chat: auth, validation, sync response, agent routing, SSE streaming, stream error handling - 6 tests for gateway sendToAgent/streamToAgent routing - Fix timingSafeEqual crash on mismatched key lengths (return 401, not 500) - Document chat endpoint in configuration.md with sync and SSE examples - Add Chat API link to docs/README.md index Written by Cameron ◯ Letta Code "First, solve the problem. Then, write the code." -- John Johnson
81 lines
5.8 KiB
Markdown
81 lines
5.8 KiB
Markdown
# LettaBot Documentation
|
|
|
|
LettaBot is a multi-channel AI assistant powered by [Letta](https://letta.com) that provides persistent memory and local tool execution across Telegram, Slack, Discord, WhatsApp, and Signal.
|
|
|
|
## Guides
|
|
|
|
- [Getting Started](./getting-started.md) - Installation and basic setup
|
|
- [Self-Hosted Setup](./selfhosted-setup.md) - Run with your own Letta server
|
|
- [Configuration Reference](./configuration.md) - All config options
|
|
- [Commands Reference](./commands.md) - Bot commands reference
|
|
- [CLI Tools](./cli-tools.md) - Agent/operator CLI tools
|
|
- [Chat API](./configuration.md#chat-endpoint) - HTTP endpoint for programmatic agent access
|
|
- [Scheduling Tasks](./cron-setup.md) - Cron jobs and heartbeats
|
|
- [Gmail Pub/Sub](./gmail-pubsub.md) - Email notifications integration
|
|
- [Railway Deployment](./railway-deploy.md) - Deploy to Railway
|
|
- [Releasing](./releasing.md) - How to create releases
|
|
|
|
### Channel Setup
|
|
- [Telegram Setup](./telegram-setup.md) - BotFather token setup
|
|
- [Slack Setup](./slack-setup.md) - Socket Mode configuration
|
|
- [Discord Setup](./discord-setup.md) - Bot application setup
|
|
- [WhatsApp Setup](./whatsapp-setup.md) - Baileys/QR code setup
|
|
- [Signal Setup](./signal-setup.md) - signal-cli daemon setup
|
|
|
|
## Architecture
|
|
|
|
LettaBot uses a **single agent with unified memory** across all channels:
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────────────┐
|
|
│ Your Server / Machine │
|
|
│ │
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ ┌───────┐ │
|
|
│ │ Telegram │ │ Slack │ │ Discord │ │ WhatsApp │ │ Signal│ │
|
|
│ │ (grammY) │ │ (Socket) │ │ (Gateway) │ │(Baileys) │ │ (CLI) │ │
|
|
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └────┬─────┘ └───┬───┘ │
|
|
│ │ │ │ │ │ │
|
|
│ └───────────────┴───────────────┴──────────────┴────────────┘ │
|
|
│ │ │
|
|
│ ┌─────────▼─────────┐ │
|
|
│ │ LettaBot Core │ │
|
|
│ │ (TypeScript) │ │
|
|
│ │ │ │
|
|
│ │ • Message Router │ │
|
|
│ │ • Session Mgmt │ │
|
|
│ │ • Heartbeat/Cron │ │
|
|
│ └─────────┬─────────┘ │
|
|
│ │ │
|
|
│ ┌─────────▼─────────┐ │
|
|
│ │ Letta Code SDK │ │
|
|
│ │ (subprocess) │ │
|
|
│ │ │ │
|
|
│ │ Local Tools: │ │
|
|
│ │ • Read/Glob/Grep │ │
|
|
│ │ • Bash │ │
|
|
│ │ • web_search │ │
|
|
│ └─────────┬─────────┘ │
|
|
└────────────────────────────────────┼──────────────────────────────────────┘
|
|
│ Letta API
|
|
▼
|
|
┌──────────────────────────┐
|
|
│ Letta Server │
|
|
│ (api.letta.com or │
|
|
│ self-hosted Docker) │
|
|
│ │
|
|
│ • Agent Memory │
|
|
│ • LLM Inference │
|
|
│ • Conversation History │
|
|
└──────────────────────────┘
|
|
```
|
|
|
|
## Key Features
|
|
|
|
- **Multi-Channel** - Chat across Telegram, Slack, Discord, WhatsApp, and Signal
|
|
- **Unified Memory** - Single agent remembers everything from all channels
|
|
- **Persistent Memory** - Conversations persist across days/weeks/months
|
|
- **Local Tool Execution** - Agent can search files, run commands on your machine
|
|
- **Voice Messages** - Automatic transcription via OpenAI Whisper
|
|
- **Streaming Responses** - Real-time message updates as the agent thinks
|
|
- **Background Tasks** - Heartbeats and cron jobs for proactive actions
|