Moltbot Telegram Setup: Bot API Guide

Moltbot on Telegram

The Telegram channel is production-ready for bot DMs + groups via grammY. Long-polling is the default; webhook mode is optional. It offers deterministic routing, meaning replies always return to the correct chat, and the model never has to "guess" the delivery channel.

Quick Setup (Fast Path)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing"
    }
  }
}

How It Works

Creating Bot Token (BotFather)

Privacy Mode & Groups

Access Control (DMs + Groups)

moltbot pairing approve telegram <CODE>

Group Activation Modes

By default, the bot only responds to mentions in groups (@botname or patterns in mentionPatterns). To change this behavior:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": { "requireMention": false },  // always respond
        "*": { "requireMention": true }  // default for all other groups
      }
    }
  }
}

Native & Custom Commands

Moltbot registers native commands like /status, /reset, /model with Telegram's bot menu on startup. Custom commands can be added via config:

{
  "channels": {
    "telegram": {
      "customCommands": [
        { "command": "backup", "description": "Git backup" },
        { "command": "generate", "description": "Create an image" }
      ]
    }
  }
}

Inline Buttons & Callbacks

Telegram supports inline keyboards with callback buttons. When a user clicks a button, the callback_data is delivered back to the agent as a message.

{
  "action": "send",
  "channel": "telegram",
  "to": "123456789",
  "message": "Choose an option:",
  "buttons": [
    [
      {"text": "Yes", "callback_data": "yes"},
      {"text": "No", "callback_data": "no"}
    ],
    [
      {"text": "Cancel", "callback_data": "cancel"}
    ]
  ]
}

Sticker Caching & Search

Moltbot supports receiving and sending Telegram stickers with intelligent caching. When a user sends a Static Sticker (WEBP), Moltbot uses vision to describe it. This description is saved to sticker-cache.json.

Forum Topics & Threading

Telegram forum topics include a message_thread_id per message. Moltbot appends :topic:<threadId> to the session key so each topic is isolated. Topic-specific configuration is available under channels.telegram.groups.<chatId>.topics.<threadId>.

Draft Streaming

Telegram can stream draft bubbles while the agent is generating a response (Telegram Bot API 9.3+). Moltbot uses sendMessageDraft and then sends the final reply as a normal message.

Reaction Notifications

Telegram reactions arrive as separate message_reaction events. Moltbot converts them to system events and enqueues them in the conversation history.

{
  "channels": {
    "telegram": {
      "reactionNotifications": "all",  // off | own | all
      "reactionLevel": "minimal"       // off | ack | minimal | extensive
    }
  }
}

Audio Messages (Voice vs File)

Telegram distinguishes voice notes (round bubble) from audio files (metadata card). Moltbot defaults to audio files for backward compatibility.

Limits & Retry Policy

Full Config Reference

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "allowFrom": ["123456789"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["987654321"],
      "textChunkLimit": 4000,
      "chunkMode": "length",
      "mediaMaxMb": 5,
      "historyLimit": 50,
      "replyToMode": "first",
      "streamMode": "partial",
      "linkPreview": true,
      "reactionNotifications": "own",
      "reactionLevel": "ack",
      "groups": {
        "*": { "requireMention": true },
        "-1001234567890": {
          "requireMention": false,
          "skills": ["search", "docs"],
          "systemPrompt": "Keep answers short.",
          "topics": {
            "123": { "requireMention": true }
          }
        }
      },
      "capabilities": {
        "inlineButtons": "allowlist"
      },
      "actions": {
        "reactions": true,
        "sendMessage": true,
        "deleteMessage": true,
        "sticker": false
      },
      "retry": {
        "attempts": 3,
        "minDelayMs": 500,
        "maxDelayMs": 30000,
        "jitter": 0.1
      },
      "customCommands": [
        { "command": "backup", "description": "Git backup" }
      ]
    }
  }
}

Troubleshooting