school Beginner Basics

BotFather Deep Dive: Creating Bots, API Tokens, Commands & Permissions Architecture

verified_user TGWAY Editorial Staff • calendar_today Published Sep 11, 2026 • visibility 2,940 Views

Module 08: Bots, TMA Mini Apps & Web3 TON Ecosystem

Step 086: BotFather Deep Dive: Creating Bots, API Tokens, Commands & Permissions

← Prev: Step 085 Curriculum Index Next: Step 087 →

86% Complete (86/100) • Module 08 Kickoff

Every automated service, Telegram Mini App (TMA), Web3 payment integration, and community moderation tool begins its lifecycle in one place: @BotFather, Telegram's official bot registry and management authority. BotFather is not merely a conversational interface for generating API keys; it is the master architectural control plane that governs your bot's cryptographic authentication tokens, group privacy sandboxing, slash command menus, inline query delegates, and default administrative privileges. Misconfiguring privacy mode can completely blind an anti-spam bot to chat text, while exposing an API token grants bad actors absolute control over your bot and any channels where it holds administrative status. In this masterclass guide, we deconstruct the complete anatomy of BotFather, token security best practices, command scopes, and permissions engineering.

Figure 86.1: BotFather Master Control Plane, Token Structure & Permission Scopes. TELEGRAM 186 • BOT ARCHITECTURE

1. Anatomy of BotFather (@BotFather): Registration & Lifecycle

To prevent impersonation and phishing, always verify you are conversing with the official @BotFather account, which carries Telegram's blue verified checkmark. All other accounts claiming to be BotFather are credential-harvesting phishing scams.

The 4-Step Bot Creation Protocol

Initiate Command: Send /newbot to @BotFather.
Choose Display Name: Enter a friendly, human-readable name (e.g., TGWAY Sentinel Bot). This can be changed later at any time using /setname.
Assign Unique Username: Enter a globally unique username. Strict Requirement: The username must end with either bot or _bot (case-insensitive, e.g., tgway_sentinel_bot). Bot usernames are permanent and cannot be changed without deleting and recreating the bot.
Receive Cryptographic Token: BotFather immediately generates a 45-character HTTP Bot API authentication token. Store this token in a secure environment variable.

2. Anatomy of the Bot API Token: Vault Security & Revocation

A Telegram Bot API token is composed of two distinct segments separated by a colon (:):

        7128392819:AAHq_kM79eZ48sYw10vPQRsTU93284xzyAA
      

Segment 1: Numerical Bot ID (7128392819)

The permanent 64-bit Telegram user identifier assigned to the bot. This number never changes, even if you revoke the token.

Segment 2: Cryptographic Secret Key

A 35-character cryptographically random alphanumeric string that authenticates all MTProto Bot API requests.

Zero-Client Exposure

Never embed the Bot Token in frontend React/Vue code, iOS/Android APKs, or public GitHub repositories. Anyone with this string can delete messages and hijack channels.

Instant /revoke Invalidation

If a token is compromised, open @BotFather → send /revoke → select bot. The old key terminates with 0ms propagation delay.

Dedicated Bot API Server

For enterprise deployments handling files up to 2,000 MB (vs. 20 MB cloud limit), run an official open-source local Bot API server instance with HTTP endpoint overrides.

3. Bot Privacy Mode: Sandboxed vs. Unrestricted Group Ingestion

By default, Telegram enforces strict user privacy by sandboxing bots inside group chats. Understanding this distinction is critical for developers:

Default Configuration

Privacy Mode: ENABLED

Receives messages starting with a slash command (e.g. /start).
Receives replies that quote one of the bot's own messages.
Receives messages that explicitly mention @botusername.
Receives service messages (user joined, left, pinned message).
BLOCKED: All ordinary conversation messages between group members are dropped by Telegram MTProto before reaching your server.

Custom Override (/setprivacy)

Privacy Mode: DISABLED

Receives 100% of all messages, photos, links, documents, and stickers sent by any user in the group.
Essential for anti-spam filters, keyword moderators, profanity detectors, and AI chat assistants.
Important Note: If the bot is already an administrator in a supergroup, it receives all messages regardless of privacy mode setting.

Interactive Lab Simulator

BotFather Command Engine & Token Security Inspector

ENGINE: BOTFATHER_V4_EMU

Bot Parameters Configuration

Bot Display Name:

Bot Username (Must end with 'bot'):

Group Privacy Mode:

Bot Capabilities:

Allow Group Invites (/setjoingroups: ENABLE) Enable Inline Queries (/setinline: ENABLE)

TGWAY Sentinel

@tgway_sentinel_bot

Status: UNREGISTERED • Privacy: ENABLED • Groups: ALLOWED

            BOTFATHER CONSOLE STREAM
            STANDBY
          
            Ready to interact with @BotFather API server...

5. Complete System Architecture Blueprint: BotFather Ecosystem

Inspect the comprehensive architectural infographic detailing registration flows, cryptographic token dissection, group privacy filtering, and command menu hierarchies:

Click to Enlarge High-Res Blueprint

Figure 86.2: Full 2:3 Masterclass Infographic Summary. Click to inspect high-resolution vector details.

6. Bot Profile & Permission Matrix across Telegram Bot Typologies

Bot Typology	Privacy Mode	Group Joins	Inline Queries	Required Permissions
Personal Assistant / DM Bot	Enabled	Disabled (/setjoingroups)	Optional	Standard user DM chat rights
Group Anti-Spam / Moderator	Disabled	Enabled	Disabled	Delete Messages, Ban Users, Restrict Members
Channel Broadcast Poster	N/A (Channel context)	N/A	Disabled	Post Messages, Edit Messages
TMA WebApp Launcher Bot	Enabled	Optional	Enabled (/setinline)	Menu Button WebApp URL, Stars Payment rights

7. Frequently Asked Questions (FAQ)

Q1: Can I change my bot's @username after creation?

No. Telegram Bot API does not permit changing a bot's username once registered with BotFather. You can change its display name (/setname), description, and avatar, but if you require a different @username_bot, you must delete the existing bot via /deletebot and create a new one. Note that deleting a bot is irreversible and invalidates all existing user chat histories.

Q2: What happens to active webhooks when I revoke a Bot Token?

When you execute /revoke in BotFather, the previous token is instantly severed from the MTProto router. Any existing active webhook endpoints will immediately begin failing with 401 Unauthorized: Unauthorized bot token. You must update the token in your backend server's environment configuration and re-execute setWebhook using the newly issued token.

Q3: How many commands can I register with /setcommands?

You can register up to 100 commands per bot scope. Each command name can be 1 to 32 characters (containing only lowercase English letters, numbers, and underscores). Descriptions can be up to 256 characters. You can also use the Bot API method setMyCommands to define different command menus based on language code or chat scope (e.g. showing admin commands only to group administrators).

Q4: Why does my bot not respond to commands in a supergroup?

In groups with multiple bots, Telegram requires users to qualify commands with the bot's username: /start@my_bot instead of plain /start. If Privacy Mode is enabled and a user sends an unqualified command intended for another bot, your bot will ignore it. Ensure your bot parser handles both /command and /command@your_bot syntax.

Q5: What is the maximum file size a bot can upload or download?

Via standard cloud Bot API servers (api.telegram.org), bots are restricted to 50 MB for outbound uploads and 20 MB for inbound downloads. However, if you deploy your own self-hosted local Bot API server instance, you unlock the full Telegram MTProto payload limits of up to 2,000 MB (2 GB).

MODULE 08 • FOUNDATION ESTABLISHED Next Architecture Milestone: Step 087

Ready for Step 087: Inline Bots Architecture (@gif, @pic & Inline Queries Engine)

Now that your bot identity is registered and your API token vault secured, discover how to transform your bot into a universal, frictionless inline service that any Telegram user can invoke in any chat, group, or channel simply by typing your handle.

Continue to Step 087 (Inline Bots Architecture) →

← Prev: [Telegram 185] Channel Automation & Auto-Posting Bots Next: [Telegram 187] Inline Bots Architecture: @gif, @pic & Inline Queries →