Skip to main content
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