Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HKUDS/nanobot/llms.txt

Use this file to discover all available pages before exploring further.

Telegram is the recommended chat platform for nanobot due to its excellent bot API, reliability, and ease of setup.

​
Features

  • ✅ Simple bot token authentication
  • ✅ Voice message transcription (when Groq provider is configured)
  • ✅ Media attachment support
  • ✅ Group chat with configurable reply behavior
  • ✅ SOCKS5/HTTP proxy support
  • ✅ Message quoting

​
Setup

1

Create a bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts
  3. Choose a name and username for your bot
  4. Copy the bot token (format: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)
2

Find your User ID

Your User ID is shown in Telegram settings as @yourUserId.Copy this value without the @ symbol for the config file.Alternatively, message your bot and check the nanobot logs — it will show the user ID of incoming messages.
3

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
4

Start the gateway

nanobot gateway
You should see:
Telegram channel connected
5

Test the connection

  1. Find your bot in Telegram by searching for its username
  2. Start a chat and send a message
  3. Your bot should respond!

​
Configuration Options

​
enabled
boolean
required
Enable the Telegram channel
​
token
string
required
Bot token from @BotFather (format: 1234567890:ABC...xyz)
​
allowFrom
array
default:"[]"
List of user IDs or usernames allowed to interact. Empty array = allow all users.Examples:
  • User ID: ["123456789"]
  • Username: ["alice"] (without @ symbol)
  • Multiple: ["123456789", "alice", "bob"]
​
proxy
string
default:"null"
HTTP or SOCKS5 proxy URL for regions where Telegram is blockedExamples:
  • HTTP: "http://127.0.0.1:7890"
  • SOCKS5: "socks5://127.0.0.1:1080"
​
replyToMessage
boolean
default:"false"
If true, bot replies will quote the original message

​
Voice Messages

When the Groq provider is configured, nanobot automatically transcribes voice messages using Whisper: 
{
  "providers": {
    "groq": {
      "apiKey": "gsk_..."
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "..."
    }
  }
}
Send a voice message to your bot and it will transcribe and process it!

​
Group Chat

  1. Add your bot to a group
  2. The bot responds to all messages by default
  3. To require @mentions, add a groupPolicy setting:
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "...",
      "allowFrom": [],
      "groupPolicy": "mention"
    }
  }
}
Group policy is a custom extension and may require nanobot ≥ v0.2.0

​
Proxy Configuration

For regions where Telegram is blocked: 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "...",
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

​
Troubleshooting

  1. Check the bot token is correct
  2. Verify your user ID is in allowFrom list
  3. Check gateway logs: nanobot gateway -v
  4. Make sure you’ve started a conversation with /start
If Telegram is blocked in your region:
  1. Set up a proxy (HTTP/SOCKS5)
  2. Add proxy field to config
  3. Restart the gateway
Voice transcription requires:
  1. Groq provider configured with API key
  2. Gateway restart after adding Groq config
Check logs for transcription errors.
Make sure allowFrom is an array, not a string:❌ Wrong: "allowFrom": "123456789"✅ Correct: "allowFrom": ["123456789"]

​
Complete Example

Full configuration with all options: 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
      "allowFrom": ["123456789", "alice"],
      "proxy": null,
      "replyToMessage": false
    }
  },
  "providers": {
    "groq": {
      "apiKey": "gsk_..."
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us