Skip to main content

Connect Telegram to nanoinfra

This guide connects one Telegram bot to nanoinfra. Messages sent to that bot use your normal nanoinfra model, tools, memory, and workspace.

What this guide builds​

  • a Telegram bot created through BotFather
  • the telegram channel enabled in nanoinfra
  • a running nanoinfra gateway
  • one pairing-approved Telegram account

Prerequisites​

  • A working nanoinfra CLI reply:
nanoinfra agent -m "Hello!"
  • A Telegram account.
  • A bot token from @BotFather.

Install nanoinfra​

Quick Start ranks four install methods easiest first. This is the first of them. Use pip, Docker or a source checkout instead if you prefer, and come back here.

uv tool install nanoinfra
nanoinfra onboard --wizard

Connect Telegram in the WebUI​

Start the WebUI:

nanoinfra webui

Open Settings → Channels → Telegram:

  1. If Telegram support is not installed, turn on its switch and confirm the installation.
  2. Paste the token from BotFather.
  3. If the gateway cannot reach Telegram directly, expand Advanced and enter an HTTP or SOCKS proxy such as http://127.0.0.1:7890.
  4. Save and enable Telegram.

The configuration badge appears as soon as a bot token is saved. A connection check is separate. If Telegram is temporarily unreachable, the saved configuration remains valid. The bot keeps working in an environment where the gateway has network access.

Saved tokens and proxy URLs are masked. A proxy entered here is used both for the connection check and for normal Telegram traffic.

Manual setup​

For a headless installation, install Telegram support:

nanoinfra plugins enable telegram

Then merge this snippet into ~/.nanoinfra/config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

Omit proxy when the gateway can reach Telegram directly.

Omitting allowFrom enables pairing-only mode. The first DM from a new user gets a pairing code instead of agent access.

Telegram uses long polling by default. Webhook mode is available for public HTTPS deployments. Start with long polling for the first test.

Run nanoinfra gateway​

nanoinfra channels status
nanoinfra gateway

Leave the gateway running while you test messages.

Test a message​

Open Telegram, DM the bot, and send:

Hello from Telegram

The bot should reply with a pairing code. Approve that code from an already trusted surface, such as the local CLI, and not the example below:

nanoinfra agent -m "/pairing approve <the code the bot sent you>"

If you missed the code, list the pending requests:

nanoinfra agent -m "/pairing"

Send the message again after approval. The reply should use the same model and workspace as your local CLI check.

Security notes​

  • Prefer pairing-only mode for first setup. Add allowFrom only when you want a static allowlist instead of code approval.
  • Do not use allowFrom: ["*"] unless the bot is isolated or intentionally public.
  • Rotate the BotFather token if it is pasted into logs or shared files.
  • Review tool access before adding group chats or more users.

Troubleshooting​

  • If the channel is not listed, run nanoinfra plugins enable telegram again in the same Python environment.
  • If the WebUI shows a saved configuration but the live check cannot reach Telegram, the token is still saved. Confirm the gateway can reach api.telegram.org, or open Advanced → Network proxy and enter a proxy.
  • If Telegram rejects the token, copy the current token from BotFather or regenerate it.
  • If messages do not arrive, run nanoinfra gateway --verbose and confirm the Telegram channel is enabled.
  • If a first DM returns a pairing code, that is expected. Approve the code before testing normal agent replies.
  • If Telegram Web shows unsupported rich messages, keep richMessages disabled.

Next: memory, automations, MCP tools​