Telegram Setup

Telegram is the channel most people start with. It's the most tested, most stable, and honestly the easiest to get running. If you're new to Moltbot, start here.

Create Your Bot

You need a Telegram bot. Telegram makes this weirdly easy compared to every other platform.

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Pick a display name (anything you want)
4. Pick a username (must end in bot — like mycoolbot or my_cool_bot)
5. BotFather hands you a token

The token looks something like this:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

That token is basically a password. Treat it like one. Don't paste it into a GitHub repo. Don't send it in a group chat. Don't screenshot it and post it on Twitter. You'd be surprised how often this happens.

Set the Token

Two ways to do this.

Environment Variable (recommended)

export TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Throw that in your ~/.bashrc or ~/.zshrc so it persists between sessions.

Config File

# ~/.moltbot/config.yaml
channels:
  telegram:
    botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

The env var approach is better because you won't accidentally commit secrets to git. But the config file works fine for local-only setups.

You can also run the interactive config wizard:

moltbot configure --section telegram

It walks you through everything.

Start and Pair

Fire it up:

moltbot start

Now open Telegram and send any message to your bot. First time you do this, Moltbot will spit out a pairing code in your terminal. Something like:

[Pairing] New device requesting access.
Code: ABCD-1234
Run: moltbot pairing approve telegram ABCD-1234

Approve it:

moltbot pairing approve telegram ABCD-1234

Done. You're paired. Send another message and your bot should respond.

The pairing system exists so random strangers can't just message your bot and start running up your API bill. Which is a real thing that happens. More on that in the security guide.

Using the Bot in Groups

This is where people get tripped up.

By default, Telegram bots can't read group messages. This is a Telegram privacy feature, not a Moltbot thing. You need to disable Privacy Mode.

Disable Privacy Mode

1. Open @BotFather
2. Send /setprivacy
3. Select your bot
4. Choose Disable

Without this, your bot literally cannot see messages in the group. It's invisible. This one got me good the first time — I spent 20 minutes debugging before realizing the bot just couldn't read anything.

How the Bot Responds in Groups

By default, Moltbot only responds when you @mention it:

@mybot what's the weather today?

You can add custom trigger words too:

channels:
  telegram:
    groupMentionPatterns:
      - "@mybot"
      - "hey bot"
      - "yo bot"

A Word of Caution

Adding your bot to group chats has real security implications. Other people in the group can interact with your bot, and depending on your config, they might be able to access your memory, run tools, or worse. Read the security page before adding your bot to any group.

The short version: don't do it unless you've locked things down.

Webhook Mode

By default, Moltbot uses long polling. That means it keeps asking Telegram "any new messages? any new messages?" over and over. Works great for personal use.

If you're running Moltbot on a server with a public IP, you can switch to webhook mode. Telegram pushes messages to you instead. More efficient, slightly faster.

channels:
  telegram:
    mode: webhook
    webhookUrl: https://your-domain.com/telegram/webhook
    webhookPort: 8443

Webhooks require HTTPS. No exceptions. Use Cloudflare Tunnel, or set up nginx with Let's Encrypt.

For most people, long polling is totally fine. Don't overcomplicate things.

Troubleshooting

Bot doesn't receive messages at all

• Double-check your token. Copy-paste it again from BotFather.
• Make sure Moltbot is actually running (moltbot start and check for errors).
• If you're in China or behind a restrictive firewall, you might need a proxy. Telegram is blocked in some regions.

Bot doesn't respond in groups

Privacy Mode. 99% of the time, it's Privacy Mode. Go back to BotFather, send /setprivacy, disable it.

Bot responds slowly

Could be your LLM provider. Could be network latency. Check moltbot logs for timing info.

"Pairing code" keeps appearing

You haven't approved the device yet. Run moltbot pairing approve telegram CODE with the code shown in your terminal.

What's Next

• Memory System — teach your bot to remember things
• Security — lock things down before you go live
• Proactive Messages — let your bot message you first