Lettabot

Conversation Routing

By default, all channels share one conversation. You can switch to per-channel conversation histories.

Single-agent config (top-level):

conversations:
  mode: shared        # "shared" (default) or "per-channel"
  heartbeat: last-active  # "dedicated" | "last-active" | "<channel>"

Multi-agent config (per agent):

agents:
  - name: MyAgent
    conversations:
      mode: per-channel
      heartbeat: dedicated

Notes:

• per-channel means one conversation per channel adapter (telegram/slack/discord/etc), not per chat/user.
• Agent memory remains shared across channels; only the conversation history is separated.
• heartbeat controls which conversation background triggers use: a dedicated stream, the last active channel, or an explicit channel name.

Group Settings (Optional)

Group settings apply to Telegram, Slack, Discord, WhatsApp, and Signal.

YAML fields (per channel under channels.<name>):

• groupDebounceSec: Debounce seconds for group batching (default: 5)
• groups: Map of group IDs to config (use * as the default)
  • mode: open | listen | mention-only | disabled
  • allowedUsers: Restrict who can trigger the bot in that group
  • receiveBotMessages: Allow bot/bot messages (default: false)
• mentionPatterns: Extra regex patterns for mention detection (Telegram/WhatsApp/Signal)
• instantGroups: Group IDs that bypass batching (legacy)
• groupPollIntervalMin: Deprecated (minutes)
• listeningGroups: Deprecated (use groups.<id>.mode: listen)

Environment variables (non-interactive onboarding):
Only legacy group options are supported here; prefer editing lettabot.yaml for groups config.

• <CHANNEL>_GROUP_DEBOUNCE_SEC (seconds, e.g. 5)
• <CHANNEL>_GROUP_POLL_INTERVAL_MIN (deprecated, use _GROUP_DEBOUNCE_SEC instead)
• <CHANNEL>_INSTANT_GROUPS (comma-separated, legacy)
• <CHANNEL>_LISTENING_GROUPS (comma-separated, legacy)

Example:

channels:
  slack:
    enabled: true
    botToken: xoxb-...
    appToken: xapp-...
    groupDebounceSec: 5
    mentionPatterns: ["@mybot", "hey bot"]
    groups:
      "*": { mode: mention-only }
      "C0987654321": { mode: listen }
      "C0123456789": { mode: open, allowedUsers: ["U123"] }

Configuration File

After onboarding, config is saved to ~/.lettabot/config.yaml:

server:
  baseUrl: https://api.letta.com
  apiKey: letta_...
  agentId: agent-...

conversations:
  mode: shared
  heartbeat: last-active

channels:
  telegram:
    enabled: true
    botToken: 123456:ABC-DEF...
    dmPolicy: pairing
  
  slack:
    enabled: true
    botToken: xoxb-...
    appToken: xapp-...
    dmPolicy: pairing

Edit this file directly or re-run lettabot onboard to reconfigure.

Commands

# Setup
lettabot onboard                    # Interactive wizard
lettabot onboard --non-interactive  # Env-based setup (agent-friendly)

# Run
lettabot server                     # Start bot server

# Manage
lettabot pairing list               # List pending pairing requests
lettabot pairing approve <channel> <code>  # Approve user
lettabot skills                     # Enable/disable skills

# Scheduling
lettabot cron list                  # List scheduled tasks
lettabot cron add "Daily standup at 9am" "0 9 * * *"  # Add cron job

Troubleshooting

"Module not found" errors

Make sure you've run npm run build after installing or pulling updates.

Telegram bot not responding

1. Check token is correct: curl https://api.telegram.org/bot<TOKEN>/getMe
2. Ensure bot is started: lettabot server should show "Connected to Telegram"
3. Check access control: User may need pairing approval

Slack not receiving messages

1. Verify Socket Mode is enabled in Slack app settings
2. Check both tokens are set: SLACK_BOT_TOKEN and SLACK_APP_TOKEN
3. Ensure event subscriptions are configured (app_mention, message.im)

WhatsApp QR code not appearing

1. Make sure Signal Desktop is closed (conflicts with baileys)
2. Delete ~/.wwebjs_auth if previously used different library
3. Check no other WhatsApp Web sessions are active

Example: Agent Setup Flow

For coding agents helping users set up LettaBot:

# 1. Clone and build
git clone https://github.com/letta-ai/lettabot.git
cd lettabot
npm install && npm run build && npm link

# 2. Get Letta API key
# Guide user to app.letta.com → API Keys → Create Key

# 3. Get Telegram bot token
# Guide user to @BotFather → /newbot → follow prompts

# 4. Set environment variables
export LETTA_API_KEY="letta_..."
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
# Defaults will be used for LETTA_BASE_URL, agent name, and DM policy

# 5. Run non-interactive setup
lettabot onboard --non-interactive

# 6. Instruct user to start server
# DON'T start server automatically - user must see output
echo "Setup complete! Run 'lettabot server' to start the bot."

For WhatsApp (QR code required on first run):

export LETTA_API_KEY="letta_..."
export WHATSAPP_ENABLED="true"
export WHATSAPP_SELF_CHAT_MODE="true"  # REQUIRED: true=personal number, false=dedicated bot
lettabot onboard --non-interactive

# CRITICAL: Do NOT auto-start the server!
# Tell user: "WhatsApp setup complete. Please run 'lettabot server' in your terminal."
# User must see QR code in console output to scan it.
# After first pairing, server can be managed normally.

Agent Instructions: If an AI agent is helping with setup and WhatsApp is configured:

1. Complete lettabot onboard --non-interactive
2. DO NOT run lettabot server automatically
3. Tell user: "Setup complete! Please run lettabot server in a terminal to see the WhatsApp QR code"
4. Wait for user confirmation that QR was scanned
5. After confirmation, server can be managed normally

The agent can verify success by checking:

• lettabot server output shows "Connected to Telegram" (or other channel)
• Config file exists at ~/.lettabot/config.yaml
• User can message bot on configured channel(s)

Docker Server Letta

To use a Letta Docker server:

# Run Letta Docker
docker run -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  -p 8283:8283 \
  -e OPENAI_API_KEY="your_openai_api_key" \
  letta/letta:latest

# Configure LettaBot
export LETTA_BASE_URL="http://localhost:8283"
export LETTA_API_KEY="sk-..."  # From Letta admin panel

lettabot onboard --non-interactive

Skills Integration

LettaBot supports loading skills from:

• Clawdhub (clawdhub.com)
• skills.sh repositories
• Local .skills/ directory

# Install skill from Clawdhub
npx molthub@latest install sonoscli

# Connect to LettaBot
lettabot skills
# Space to toggle, Enter to confirm

# Skills will be available to agent