Skip to content
Bazilion

Connecting Telegram

One bot long-polls one private forum supergroup. A ⚙ bazilion service topic takes commands, and every Agent gets its own topic: your messages there become Agent turns and the replies come back. The daemon does not need to be reachable from the internet.

Part 1 — Telegram side

Section titled “Part 1 — Telegram side”

Only a person can create a bot, enable Topics and promote the bot, so these steps are manual. You do them once.

Step 1. Create a bot with @BotFather

Section titled “Step 1. Create a bot with @BotFather”
  1. Open a chat with @BotFather and send /newbot.
  2. Give it a display name and a username ending in bot.
  3. Copy the bot token it replies with, for example 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ. If you lose it, /token in @BotFather gives you a new one.

Step 2. Turn off Privacy Mode

Section titled “Step 2. Turn off Privacy Mode”
  1. In @BotFather, send /mybots and select your bot.
  2. Open Bot Settings → Group Privacy and choose Turn off.

Step 3. Create a forum supergroup

Section titled “Step 3. Create a forum supergroup”
  1. Create a new group.
  2. Open its settings → Edit and enable Topics. This makes it a forum supergroup.

Step 4. Add the bot and make it an admin

Section titled “Step 4. Add the bot and make it an admin”
  1. Add your bot to the group.
  2. Promote it to administrator with the Manage Topics permission. Bazilion uses it to create, rename, hide and close topics. Pinning messages is optional.

Step 5. Get the group’s chat id

Section titled “Step 5. Get the group’s chat id”

The chat id is a negative number such as -1001234567890. Temporarily add a helper bot such as @RawDataBot or @getidsbot, copy the -100… id it posts, and remove it again. In Telegram Web, the group URL holds the same number without the -100 prefix.

Part 2 — Save the credentials

Section titled “Part 2 — Save the credentials”

Open Setup → Integrations (/config/integrations/telegram), paste the Bot token and the Supergroup chat ID, and save. Then run preflight: it checks the bot identity, that the group is reachable and is a forum, that the bot can manage topics, and that Privacy Mode is off.

The bot token is stored encrypted. The bot starts by itself: it creates the ⚙ bazilion service topic, pins an Agent directory there, hides the General topic and registers its command menu. Hiding General makes Telegram post a one-off “closed the topic” message; that is expected.

Part 3 — Pair yourself as owner

Section titled “Part 3 — Pair yourself as owner”

Until an owner is paired, the bot answers nobody. Create a one-time code on the web page or with:

Terminal window
bazilion telegram pairing create

Send /pair <code> in the ⚙ bazilion topic within ten minutes, from your own account (not a direct message to the bot). bazilion telegram pairing status shows the owner; pairing cancel drops an unused code, and pairing reset --yes removes the owner so you can pair again.

Part 4 — Talk to your Agents

Section titled “Part 4 — Talk to your Agents”

In the ⚙ bazilion topic:

  • /talk <agent> opens (or creates) an Agent’s topic; use <team>/<agent> when names clash.
  • /spawn creates an Agent from a Profile, interactively or as /spawn <profile> [name] [in <team>].
  • /spawn_team <template> [in <team>] spawns a Team template, one topic per member.

In an Agent topic, plain messages, photos and files go to the Agent’s follow-up queue and run one turn at a time; a 👀 reaction shows the message was received. Photos reach the model as images; other files (up to 20 MB) are saved for the Agent to read.

Replies, errors, images and delivered files are mirrored into the topic. An Agent’s mirror mode (bazilion agent edit <id> --mirror minimal|verbose, or the Agent page) adds short tool-call lines in verbose mode, at most 30 a minute per Agent.

When an Agent asks a question, it appears in its topic with one button per choice and Skip. Tap a button, or reply to the question message with your own answer.

Who can use the bot

Section titled “Who can use the bot”

The paired owner, plus the people the owner adds: /allow <user id> in Telegram, the allowlist card on the web page, or bazilion telegram allow <user id>. Someone who is not on the list gets a reply with their user id to pass on. /deny, /allowed and bazilion telegram deny|allowed manage the list. Everyone on the list can chat with Agents, answer their questions and run the commands; only the owner can /allow and /deny. Removing someone also cancels the messages they still have waiting in a queue.

Anyone else in the group can still read the topics, so keep the group to people you trust. Messages from other bots and from anonymous admins are ignored.

Bot commands

Section titled “Bot commands”

In the ⚙ bazilion service topic:

CommandWhat it does
/talk <agent>Open or create an Agent’s topic
/spawnCreate an Agent from a Profile
/spawn_teamSpawn a Team template (/spawn-team works too)
/list (or /agents)Agents grouped by Team
/teamsTeams with Agent counts
/healthBot identity and polling state
/whoamiYour Telegram user id
/allowed, /allow <id>, /deny <id>The allowlist (/allow and /deny are owner only)
/helpThe command reference

In an Agent topic:

CommandWhat it does
/queue, /queue drop <n|all>List or remove waiting messages
/stopCancel the running turn; pauses the queue when messages wait
/resumeResume the queue
/closeClose the topic
/rebind <agent>Point the topic at another Agent
/unbindDetach the topic from its Agent

Topic names and icons

Section titled “Topic names and icons”

Topic names follow the Team: set a template with the tokens {agent.name}, {team.name} and {team.slug} (it must include {agent.name}) on the Team page or with bazilion team topic-format set <team> '{team.name} / {agent.name}'. Topic icons follow the Profile, or the Agent’s own --topic-icon.

Telegram can also post new Attention items to the service topic; see Attention notifications.

Troubleshooting

Section titled “Troubleshooting”
  • The bot does not answer. Pair an owner first, then check bazilion telegram health and bazilion telegram bot status. bazilion telegram bot restart (or restart bot on the web page) restarts it.
  • An Agent does not answer in its topic. Read the error in the topic or in the web chat, and check the Agent’s provider with bazilion provider test <provider:model>.
  • Preflight fails on forum topics or Manage Topics. Enable Topics (Step 3) or give the bot the permission (Step 4).
  • “Supergroup chat id changed”. Telegram migrated the group to a new id. Use Reconnect on the web page or bazilion telegram reconnect.
  • Someone deleted an Agent’s topic. Bazilion notices on the next send and clears the binding. Bind it again with /talk, the web page or bazilion telegram bind.
  • Topic links on iOS open the topic list. That is a Telegram iOS limitation; open the topic from the list.
  • A 409 conflict in the daemon log. A webhook is set on the token, or another process polls the same bot. Do not run two daemons against one bot token.
  • Clearing the credentials (bazilion telegram config clear) stops the bot and everything it sends.