Telegram Setup

Deploy Mona as a Telegram bot so you and your team can chat with her from any device.

Prerequisites

• A working MonoClaw installation
• A Telegram account
• A bot token from @BotFather

1. Create a bot with BotFather

1. Message @BotFather on Telegram
2. Send /newbot
3. Follow the prompts to name your bot
4. Copy the HTTP API token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Configure MonoClaw

Run the interactive gateway setup:

monoclaw gateway setup

Choose Telegram and paste your bot token when prompted.

Or set it manually:

monoclaw config set TELEGRAM_BOT_TOKEN "your-token-here"

3. Start the gateway

monoclaw gateway start

You should see:

✅ Telegram gateway started
   Bot: @YourBotName
   Webhook: https://your-domain.com/webhooks/telegram

4. Authorize users

By default, Mona only responds to allowed users. Add yourself:

monoclaw gateway allowlist add <your-telegram-user-id>

Find your Telegram user ID by messaging @userinfobot.

Or disable the allowlist for a public bot (not recommended for production):

# ~/.monoclaw/config.yaml
gateway:
  allowlist:
    enabled: false

5. Test it

Send a message to your bot on Telegram. Mona should reply within a few seconds.

Try these prompts:

What's on my calendar today?

Search the web for the latest HKEX announcements.

Voice messages

Mona supports voice messages in Telegram. Send a voice note and she'll transcribe it, then respond.

Enable voice mode:

monoclaw config set voice.enabled true

Group chats

Add your bot to a group chat:

1. Add @YourBotName to the group
2. Make sure the bot has permission to read messages
3. Mention the bot or reply to her messages

Group sessions are separate from DM sessions.

Webhook vs polling

MonoClaw uses webhooks by default if you have a public URL. For local development, it falls back to polling:

# ~/.monoclaw/config.yaml
gateway:
  telegram:
    mode: polling    # polling | webhook

Troubleshooting