Connecting Telegram

Bazilion can put each agent in its own Telegram forum topic inside a single supergroup: you chat with an agent by typing in its topic, and its replies mirror back there. A dedicated ⚙ bazilion topic acts as the control plane where you spawn agents and run commands.

Setup has a fair number of manual Telegram-side steps that bazilion can’t do for you (only a human can create a bot, enable forum Topics, and promote the bot to admin). This guide spells out every one of them.

Note

You only do the Telegram-side setup (Part 1) once. After that, spawning and binding agents is a single command.

What you’ll end up with

• A supergroup whose General topic is hidden, with a pinned ⚙ bazilion service topic.
• One forum topic per agent, named after the agent, with its own icon.
• Two-way chat: type in a topic → the agent runs a turn → its reply appears in the same topic.

Before you start

• A working bazilion daemon (see Getting started).
• A private forum supergroup intended for you and your bot. Keep the paired owner account distinct from anonymous/channel identities.
• A local Docker engine and compatible image on the daemon host. Telegram turns always require protected runtime readiness.
• The Telegram app, signed in to the account that will own the supergroup.
• About ten minutes.

---

Part 1 — Telegram side

Step 1. Create a bot with @BotFather

1. Open a chat with @BotFather in Telegram and send /newbot.
2. Follow the prompts: give it a display name and a username ending in bot.
3. BotFather replies with a bot token that looks like 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ. Copy it somewhere safe — you’ll paste it into bazilion later.

If you ever lose the token, get a new one from @BotFather → /token.

Step 2. Turn OFF the bot’s Privacy Mode

Bazilion’s preflight checks that Privacy Mode is off; configure it explicitly.

1. In @BotFather, send /mybots and select your bot.
2. Open Bot Settings → Group Privacy.
3. Set it to Turn off.

Telegram behavior and Bazilion preflight

Telegram administrator bots receive group messages even with Privacy Mode on. For non-admin bots, Privacy Mode limits which messages arrive. Bazilion still checks the explicit Privacy Mode setting during preflight, so turn it off as shown. See the Telegram Bots FAQ.

Step 3. Create a forum supergroup with Topics enabled

Bazilion needs a forum supergroup — a group with Topics turned on.

1. Create a new group (or use an existing one you own).
2. Open the group’s settings → Edit, and enable Topics. This converts the group into a forum supergroup.

Caution

Only the supergroup owner (a human) can enable Topics — the bot cannot do it. If Topics aren’t enabled, bazilion can’t create any topics and activation fails.

Step 4. Add the bot and make it an admin

1. Add your bot to the supergroup.
2. Promote it to administrator.
3. Grant it the Manage Topics permission. This is the one permission bazilion strictly requires — it’s used to create, rename, hide, and close forum topics.

Other admin permissions are optional. (If you also want the directory message pinned, leave the bot’s pin messages permission on — but it’s best-effort and not required.)

Step 5. Get the supergroup’s numeric chat ID

Bazilion identifies the supergroup by its numeric chat ID, which looks like -1001234567890. Telegram doesn’t show this in the UI, so use a helper:

1. Temporarily add a “get ID” bot to the group — e.g. @RawDataBot or @getidsbot. It will post the chat’s details, including an id beginning with -100.
2. Copy that -100… number.
3. Remove the helper bot from the group.

Tip

Alternatively, open the group in Telegram Web — the URL contains the internal id, and the full chat ID is that number prefixed with -100.

Caution

Bazilion does not support the “forward a message to the bot to detect the chat ID” trick — messages from any chat other than the configured supergroup are ignored. You must get the ID using one of the methods above.

---

Part 2 — Enter your credentials in bazilion

You can do this in the web UI or the CLI.

Web UI

Go to config → Integrations → Telegram (/config/integrations/telegram). In the Credentials card:

1. Paste your Bot token.
2. Paste your Supergroup chat ID (the -100… number).
3. Click save credentials.

Then click run preflight to check everything is wired up. You should see five green checks:

• Bot identity — your bot’s @username.
• Supergroup reachable — the group’s title.
• Forum topics enabled — Topics are on.
• Manage Topics — the bot is an admin with the permission.
• Privacy Mode is OFF — the bot can read group messages.

CLI

# save token + chat ID together
bazilion telegram config set --token <BOT_TOKEN> --chat <CHAT_ID>

# run the preflight checks
bazilion telegram health

# see what's stored (token is masked)
bazilion telegram config show

The bot token is stored encrypted; the chat ID is stored as plain config. Saving new credentials restarts the bot automatically (this can take ~25 seconds while the previous connection drains).

---

Part 3 — Activation (automatic)

Once credentials are saved, the daemon connects and activates the bot automatically. The first time it activates, it:

1. Creates the ⚙ bazilion service topic (your control plane).
2. Posts and pins a directory message listing your agents.
3. Hides Telegram’s built-in General topic so the service topic is the focus.
4. Registers the bot’s slash-command menu.

Activation creates the service topic, but does not authorize a human. Pair the owner there before trying to spawn or talk to an Agent.

“bazilion closed the topic”

The first time the bot hides General, Telegram posts a one-off “bazilion closed the topic” service message. This is expected and only happens once — not on every restart.

---

Part 4 — Pair the owner and check readiness

From the authenticated CLI on the Bazilion host:

bazilion telegram pairing create

In the configured supergroup, open ⚙ bazilion and send /pair <code> from your intended owner account. Do not send it in a direct message to the bot, General, or an Agent topic: initial pairing only accepts the service topic. The code is short-lived, single-use, and bound to the configured bot/group.

Check the result locally:

bazilion telegram pairing status
bazilion telegram health
bazilion doctor

Confirm the intended owner, bot/group checks, and protected-work readiness. Health also reports membership and owner presence; the supported personal setup is one owner plus the bot. If a code expired, generate a fresh one. Use bazilion telegram pairing cancel to cancel an unused code.

Telegram turns cannot use host coding tools, browser automation, or MCP. If Docker is unavailable, pairing may succeed but Agent work will fail. Follow Docker preparation before sending work.

Part 5 — Spawn and bind agents

An agent gets a Telegram topic when you bind it. The easiest way is from the ⚙ bazilion topic itself:

From Telegram

In the ⚙ bazilion topic:

• /spawn — pick a profile from the buttons, then send a name (or - to auto-name). The new agent is created and its topic is bound automatically.
• /spawn <profile> <name> — spawn immediately. Add in <team-slug> to target a non-default Team.
• /spawn_team — spawn a whole Team Template at once, one topic per member. Add in <team-slug> to target a named Team.
• /talk <agent> — open or create the topic for an agent that already exists.

Web UI

On the agent’s detail page (/agents/<id>), open the Telegram section and click bind a topic. A deep link opens the new topic in Telegram.

CLI

bazilion telegram bind <agent-id-or-prefix>
bazilion telegram list          # see all agents and their topic bindings
bazilion telegram unbind <agent>

Once an agent is bound, just type in its topic to talk to it. While it works you’ll see a “typing…” indicator and a 👀 reaction on your message that clears when the reply lands. Accepted messages are stored individually in the durable FIFO follow-up queue, retaining their conversation and attachments. Use /queue for status and explicit pause/resume controls.

Live questions require a button response, a reply to the exact prompt, or /answer <question-id> <text>. Correlated answers bypass the follow-up queue. Attention notifications are separate, default-off notices sent to the paired group’s Bazilion service topic, with quiet hours and inspectable delivery receipts.

Team Policy and Telegram

With BAZILION_TEAM_POLICY_ENFORCEMENT=on, Telegram uses the same live Team Policy as every other communication surface. Human ingress requires the Team’s user → Agent edge; the reply requires Agent → user. A missing edge denies, and an approval_required edge holds that one attempt in the communication approval queue. Configure and preview the Team policy before enabling enforcement so a missing edge does not look like a Telegram connectivity issue. The Telegram allowlist and Team Policy are independent, cumulative gates: allowlisting a human never bypasses the Team’s communication policy.

---

Access control

Initial access comes only from the pairing step above. Ordinary messages do not claim ownership, and DMs to the bot are ignored. Send commands from an identified human account in the configured supergroup; anonymous admin and channel-attributed messages are rejected.

The CLI/API retain member allowlist management for existing setups. These controls do not turn the personal owner-plus-bot profile into a supported multi-user deployment, and they do not bypass Team Policy. /allowed lists entries; an owner can manage member IDs with /allow and /deny in the service topic. The API rejects creating an owner through allow --owner: owner creation uses pairing. Do not depend on an unpaired user’s /whoami reaching the command handler; the identity gate runs first.

To change the owner, first review bazilion telegram pairing status. The explicit bazilion telegram pairing reset --yes operation clears ownership and closes ingress until you pair again. The last owner cannot be removed through ordinary member deletion.

---

Bot command reference

These run in the ⚙ bazilion service topic and appear in Telegram’s slash menu:

Command	What it does
/spawn	Create an agent from a profile (interactive or /spawn <profile> <name>).
/spawn_team	Spawn a whole Team Template at once. Accepts [in <team>]; typed /spawn-team also works.
/talk <agent>	Open or create an agent’s topic. Accepts <team>/<agent>.
/list (alias /agents)	List all Agents grouped by Bazilion Team.
/teams	List Bazilion Teams with Agent counts.
/whoami	Show the already-authorized sender’s numeric Telegram user id in the service topic.
/pair <code>	Claim initial ownership in the service topic with a locally generated one-use code.
/allowed	List allowlisted users.
/allow <id> [label]	Allow a user (owner only).
/deny <id>	Remove a user (owner only).
/health	Bot identity + polling state.
/help	Command reference.

These run inside an agent’s topic (hidden from the menu, shown in /help):

Command	What it does
/close	Close this topic (keeps the agent binding).
/rebind <agent>	Point this topic at a different agent.
/unbind	Clear this topic’s agent binding (topic stays as an orphan).

---

Topic names and icons

• In the default Team, a topic is named after the Agent (e.g. researcher). In any other Team it is team-slug › agent-name.
• A Team can override the format with a template using the tokens {agent.name}, {team.name}, and {team.slug} (it must include {agent.name}). Set it on the Team’s detail page (Telegram topic names card) or with bazilion team topic-format set <team> "<template>". Saving a new template renames existing topics you haven’t manually renamed in Telegram.
• Each agent gets an icon. You can override it per agent (the topic icon field in the agent’s Telegram section); otherwise bazilion picks a default from the Agent template name and a per-Team color.

---

Environment variables

These tune Telegram behavior (set them in the daemon’s environment):

Variable	Default	Effect
BAZILION_TELEGRAM_LOOP_BUDGET	20/60/60	Per-agent inbound rate budget (max/window/cooldown, seconds). Over budget, new messages are paused for the cooldown with one notice.
BAZILION_TELEGRAM_AGENT_THROTTLE	30/60	Per-agent outbound noise budget for verbose tool-call lines. The agent’s actual reply, errors, and fatals always get through.
BAZILION_TELEGRAM_SEND_INTERVAL_MS	200	Minimum gap between outbound sends to one supergroup (rate-limit pacing).
BAZILION_TELEGRAM_POLLING_STALL_MS	120000	If no successful poll within this window, the bot self-restarts. Set to 0 to disable.

---

Troubleshooting

The agent doesn’t respond to plain messages. Confirm the configured group and bound Agent topic, then check pairing status, telegram health, and bazilion doctor. A failed Docker/provider preflight, policy hold, or unpaired sender can prevent a turn even when Telegram is connected. Also check the Privacy Mode setting from Step 2.

Pairing never succeeds. Send a fresh code in ⚙ bazilion inside the configured group, from a non-anonymous human account. DMs and other topics cannot complete pairing.

Browser or MCP tools are missing. This is expected in Telegram protected turns. See the capability table.

Preflight fails on “Forum topics enabled”. The group isn’t a forum. The owner must enable Topics in group settings (Step 3).

Preflight fails on “Manage Topics”. The bot isn’t an admin, or lacks the permission — redo Step 4.

Tapping a topic deep link on iOS opens the topic list, not the topic. This is an iOS Telegram limitation with no bot-side workaround — open the topic manually from the list. Desktop, web, and Android work as expected.

Someone deleted an agent’s topic. Bazilion notices on the next send, clears the binding, and stops mirroring there. Re-bind with /talk, the web bind a topic button, or bazilion telegram bind.

The bot is healthy and the user is allowed, but a message is denied or held. When Team Policy enforcement is on, inspect the Team’s Activity tab for a durable denial or /approvals (or bazilion approval list) for a pending attempt. Telegram access control does not override policy.

A media file was rejected. Bazilion downloads inbound media up to 20 MB. Images become model vision input; documents, audio, and video become saved files. Audio/video are not native multimodal input. Larger downloads are rejected.

“Supergroup chat id changed” banner. Telegram migrated your group to a new id. Click Reconnect in the web UI (or run bazilion telegram reconnect) to repoint bazilion and re-activate in the new group.

A 409 conflict in the logs. Either a webhook is set on the token or a second process is polling the same bot. Don’t run two daemons against one bot token.