Building Telegram Bots

Purpose

Prevent stale-knowledge failures when writing Telegram bot code. The Telegram Bot API updates roughly quarterly; frameworks update even more frequently. Training-time knowledge is unreliable. This skill enforces a verification protocol — detect, fetch, confirm — before any bot code is generated.

Scope

Covered: python-telegram-bot, aiogram (Python); grammY, Telegraf (Node.js)

Not covered: Other languages or frameworks; Telegram client API (TDLib); bot deployment and hosting; payment and monetisation APIs

Verification Protocol

Run this protocol before writing any bot code. Do not skip steps.

Step 1 — Detect the project framework and version

Read the project dependency manifest:

• Python project: check pyproject.toml first, then requirements.txt
• Node.js project: read package.json → dependencies and devDependencies

Identify which framework is present and its pinned or constrained version. If a lock file exists (package-lock.json, poetry.lock, uv.lock), read it for the exact resolved version.

See references/framework-guide.md → "Detecting Framework Version from Project Files" for manifest patterns.

Step 2 — Identify the Bot API version the framework targets

Map the framework version to its supported Bot API version.

See references/framework-guide.md → "Framework Fact Sheets" for the current mapping table.

Staleness warning: If the project uses Telegraf v4.x, issue an explicit warning before proceeding. See references/framework-guide.md → "Telegraf Staleness Warning" for required warning text.

Step 3 — Fetch the current Bot API changelog

Fetch https://core.telegram.org/bots/api#recent-changes to identify the current Bot API version. Compare it to the version the project's framework targets. Note any gap.

If the user is asking about a feature introduced in a Bot API version newer than the framework's support ceiling, tell them the framework does not yet support it.

Step 4 — Fetch framework-specific documentation for the feature being built

Do not rely on training knowledge for method signatures, handler registration patterns, or type names. Fetch the framework's current documentation for the specific feature.

See references/framework-guide.md → "Framework Documentation URLs" for the correct URL per framework.

For versioned docs (python-telegram-bot, aiogram), use the URL pattern for the exact version found in Step 1 — not the "latest" or "stable" alias, unless the installed version matches it.

Step 5 — Confirm all patterns are async

All current framework major versions use async/await. Synchronous bot code indicates a v13-era python-telegram-bot pattern (or aiogram v2). If the installed version is v20+ (python-telegram-bot) or v3+ (aiogram), all handler callbacks must be async def and all API calls must be awaited.

Step 6 — Write the code

Write code only after completing Steps 1–5. Reference the fetched documentation, not training memory, for method signatures and parameter names.

Common Pitfalls

Read `references/framework-guide.md` → "Migration Traps" before working on projects that show signs of a version upgrade. Signs include mixed sync/async patterns, old import paths, or a dependency version bump in git history.

For rate limit and webhook storm patterns, see references/telegram-bot-api.md → "Operational Limits" and "Webhook Storm Prevention".

New Bot Projects — Framework Recommendation

When starting a new bot (no existing project manifest):

• Python: Prefer aiogram (most current Bot API support among Python frameworks). python-telegram-bot is also well-maintained.
• Node.js: Use grammY. Do not start new projects with Telegraf v4.

Confirm the recommendation by checking references/framework-guide.md → "Framework Fact Sheets" for current maintenance status before advising.

Reference Files

Read these files when the verification protocol directs you to them. Do not load both upfront — load on demand.

• references/telegram-bot-api.md — Bot API structure, section anchors, operational limits, webhook vs polling
• references/framework-guide.md — Framework fact sheets, detection algorithms, documentation URLs, migration traps

These reference files contain version-specific data last verified on the date shown at the top of each file. If significant time has passed since that date, treat the framework versions and Bot API mappings as approximate and verify against the URLs provided in each file.

Evaluation Scenarios

Scenario 1 — Existing Python project, unknown version User asks to add a message handler to an existing project. Measurable outcome: agent does not use training-memory method signatures; all method names and parameter names in the generated code match the fetched documentation for the detected framework version.

Scenario 2 — User asks to add reactions to a Telegraf project Agent detects Telegraf v4 in package.json and issues the staleness warning before writing any code. Agent does not attempt to scaffold or suggest code using post-7.1 API features. User receives an explicit statement that the feature requires grammY or a framework upgrade.

Scenario 3 — New Node.js bot from scratch No manifest to read. Agent scaffolds with grammY (not Telegraf). Generated code uses async patterns; all API calls are awaited. No training-memory method signatures appear — code derives from fetched grammY docs.

Scenario 4 — Python project with synchronous handlers Agent detects python-telegram-bot v20+ in the manifest, then flags the synchronous handlers as incompatible before rewriting. Rewritten code uses Application (not Dispatcher) and async def callbacks. Agent fetches the v20 migration guide rather than relying on training memory.