Support Bot API 9.6 by Leask · Pull Request #2092 · telegraf/telegraf

Leask · 2026-05-05T18:30:33Z

Summary

This PR updates Telegraf for Telegram Bot API 9.6 and uses v6 as the forward-looking migration point: keep the v4 programming model where it still fits, align the runtime with the official Bot API surface, and modernize the infrastructure around current Node.js.

updates the package to v6.0.0 and documents the release in release-notes/6.0.0.md
temporarily uses the published registry alias @telegraf/types: npm:@leask/types@9.6.0 for the Bot API 9.6 declarations until Support Bot API 9.6 types types#14 is merged or published upstream
treats the official @telegraf/types API declarations as the source of truth for future Bot API sync work
adds runtime wrappers for every typed official Bot API method, with coverage tests that detect drift between @telegraf/types and Telegram
adds recursive nested InputFile multipart support for newer media payloads
modernizes the runtime/tooling baseline for Node.js >=20: native globalThis.fetch by default, no hard node-fetch dependency, p-timeout 7, ESLint 9 flat config, TypeScript 6, AVA 8, and current GitHub Actions
keeps edge networking extensible through injectable telegram.fetch for proxy agents, custom TLS, compression, or other non-standard fetch behavior
preserves native fetch errors during token redaction, including getter-only DOMException fields from aborted native fetch calls
folds in issue/PR cleanup for configurable request timeout, optional polling 409 retry, safer launch callback timing, default empty sessions, and scene typing exports/inference
removes the planning document in favor of release notes

Future direction

The intended maintenance path after this PR is to make future Telegram Bot API updates mostly mechanical: update the official type declarations, let the API coverage tests identify missing runtime wrappers or request shapes, and keep Telegraf close to Telegram's canonical API definitions.

The infrastructure direction is similarly conservative and modern: prefer platform standards available in supported Node.js releases, avoid bundling compatibility shims by default, and keep advanced behavior injectable instead of hard-wired. For networking, that means native fetch for the common path and user-supplied telegram.fetch for specialized deployments.

Validation

npm ci
npm test (181 passing)
npm run lint
npm run build:docs (passes with existing TypeDoc warnings)
npm audit (0 vulnerabilities)
git diff --check
npm pack --dry-run
native fetch behavior is covered by tests for default multipart upload, custom Bot API fetch, custom URL attachment fetch, multipart duplex: 'half' propagation, request timeout aborts, getter-only native error redaction, and globalThis.fetch typing
direct node-fetch dependency is removed; remaining node-fetch in the lockfile is only transitive through unrelated tooling

Notes

The companion types PR is telegraf/types#14. Until the upstream types release lands, this branch uses the published temporary registry alias @telegraf/types: npm:@leask/types@9.6.0, so installs resolve from npm packages only. Before this PR is merged upstream, that alias should be replaced with the accepted upstream branch or the official published @telegraf/types release.

Recent issue-sweep follow-up is commit 327d7d3. PR review follow-up is commit e1a42d7. Native fetch cleanup is commit 15c5531; docs/test completeness follow-up is commit 07a9ef3. Temporary npm alias follow-up is commit 41ee6c9. Native error redaction fix is commit 088144f.

BREAKING! thumbnail is now required, even if it's undefined

…`reply_parameters` fix telegraf#1970

- Return 405 Method Not Allowed for non-POST requests - Return 404 Not Found for webhook path mismatches - Return 403 Forbidden for secret token mismatches (unchanged) Previously all rejection scenarios returned 403, which confused clients into thinking there was an authentication issue when the problem was actually a method or path mismatch. Fixes telegraf#2065

Snyk has created this PR to upgrade debug from 4.3.5 to 4.4.0. See this package in npm: debug See this project in Snyk: https://app.snyk.io/org/mkrhere/project/ed7a22df-dd63-45d9-a5e4-363f448cb5dc?utm_source=github&utm_medium=referral&page=upgrade-pr

Copilot

Pull request overview

Updates Telegraf to a v6.0.0 release line aligned with Telegram Bot API 9.6, adding runtime coverage for newly typed API methods and modernizing Node.js/tooling requirements (Node >= 20).

Changes:

Added runtime wrappers for newer/typed Bot API methods (plus supporting Context helpers) and expanded multipart handling to support nested InputFile values.
Modernized runtime/tooling dependencies and CI (node-fetch v3, p-timeout v7, ESLint 9 flat config, TS 6, AVA 8, updated workflows).
Added/updated tests and docs/release notes for the v6 line.

Reviewed changes

Copilot reviewed 31 out of 37 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsconfig.json	Updates TypeDoc configuration (notably removing `media`).
test/telegraf.js	Updates AVA import style and adds webhook status-code tests.
test/scenes.js	Updates AVA import style.
test/markup.js	Updates AVA import style.
test/format.js	Updates AVA import style.
test/compactOptions.js	Updates AVA import style.
test/api.js	Adds API/type sync tests and nested multipart serialization test coverage.
src/telegram.ts	Adds Bot API 9.6 wrappers and expands poll option input support.
src/telegram-types.ts	Adds `ExtraPaidMedia` helper type.
src/telegraf.ts	Adjusts webhook callback integration and updates `p-timeout` usage.
src/scenes/wizard/index.ts	Formatting/type-parameter layout adjustments.
src/scenes/wizard/context.ts	Formatting/type-parameter layout adjustments.
src/scenes/context.ts	Formatting/type-parameter layout adjustments.
src/reactions.ts	Adds support for new reaction types (e.g., paid).
src/filters.ts	Formatting/type layout adjustments.
src/core/types/typegram.ts	Adds `InputPaidMedia` alias.
src/core/network/webhook.ts	Adds options for more specific webhook rejection status codes.
src/core/network/polling.ts	Removes AbortController dependency (Node 20+ globals).
src/core/network/client.ts	Migrates to node-fetch v3 patterns, adds request timeouts, improves multipart recursion.
src/core/helpers/util.ts	Removes ESLint disables; keeps existing helper types.
src/core/helpers/formatting.ts	Formatting/type-parameter layout adjustments.
src/core/helpers/args.ts	Refactors for clearer control flow.
src/context.ts	Adds business update accessors and propagates business connection IDs in send helpers.
src/composer.ts	Formatting/type layout adjustments.
src/cli.mts	Minor catch syntax update.
release-notes/6.0.0.md	Adds v6.0.0 release notes.
README.md	Updates docs to describe v6 and Bot API 9.6 support; refreshes links/features.
package.json	Bumps to v6.0.0, raises Node engine requirement, updates dependencies/devDeps.
eslint.config.mjs	Adds ESLint 9 flat config.
build/expose.ts	Stops generating `.eslintignore` as part of build tooling.
.npmignore	Ignores local env/config files from npm package.
.gitignore	Ignores local env/config files from git.
.github/workflows/release.yml	Updates release workflow for v6 and refreshed actions/steps.
.github/workflows/node.js.yml	Updates CI Node matrix and actions/steps.
.github/workflows/lock.yml	Updates lock-threads action version.
.eslintignore	Removes legacy ignore file (replaced by flat config ignores).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Leask · 2026-05-05T21:07:39Z

Issue/PR sweep follow-up pushed in commit 327d7d3.

Covered in this follow-up:

optional polling retry for transient 409 Conflict startup races
launch callback ordering so immediate bot.stop() no longer races startup state
configurable telegram.requestTimeout
supported custom telegram.fetch, including globalThis.fetch type compatibility and Web ReadableStream URL attachments
session() defaulting new keyed sessions to {} when defaultSession is omitted
scene type polish: exported Scenes.SceneOptions, protected SceneContextScene internals for subclasses, and typed ctx.scene.state inference from custom scene session data

Validation after the commit:

npm test (178 passing)
npm run lint
npm run build:docs (passes with existing TypeDoc warnings)
npm audit --audit-level=moderate (0 vulnerabilities)
npm pack --dry-run
git diff --check

siakinnik · 2026-05-07T16:31:25Z

telegraf mainteners are inactive for over a year already, will be really happy to see your PRs ported to fork @telegraf-hardened

MKRhere and others added 16 commits May 5, 2026 12:19

feat: API 7.2 [1/6]

3d64eb5

chore: update some deps & typescript

e5dd8f0

feat: API 7.2 [2/6]

757958b

feat!: take format in setStickerSetThumbnail

355b37f

BREAKING! thumbnail is now required, even if it's undefined

Add support for API v7.3-7.8

e3c30e6

fix: attachFormValue did not consider value as JSON object such as …

877d951

…`reply_parameters` fix telegraf#1970

fix: thumbnail not attached properly

cdfa82f

fix: preserve stack trace when redaction creates new Error

6b7664f

fix: add type predicate return types to Msg methods

e2f4479

feat: sync Telegraf with Bot API 9.6

68a0cb4

test: verify Bot API changelog fields

b7023f2

test: harden Bot API 9.6 PR checks

09a108e

chore: prepare v6 release docs

6ecc11d

chore: prepare Bot API 9.6 v6 PR

e5b8137

Leask marked this pull request as ready for review May 5, 2026 20:33

Copilot AI review requested due to automatic review settings May 5, 2026 20:33

Copilot started reviewing on behalf of Leask May 5, 2026 20:34 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread src/core/network/client.ts Outdated

Comment thread src/telegraf.ts Outdated

Comment thread src/core/network/webhook.ts

Comment thread test/api.js Outdated

fix: address issue sweep runtime gaps

327d7d3

Leask added 3 commits May 5, 2026 17:16

fix: address PR review feedback

e1a42d7

refactor: use native fetch by default

15c5531

test: cover custom fetch multipart options

07a9ef3

Leask mentioned this pull request May 5, 2026

[codex] Sync docs for Telegraf v6 networking feathers-studio/telegraf-docs#23

Open

Leask added 2 commits May 6, 2026 08:05

chore: use published temporary types alias

41ee6c9

fix: preserve native fetch errors during token redaction

088144f

siakinnik mentioned this pull request May 7, 2026

Roadmap v3: The Great API Sync telegraf-hardened/telegraf-hardened#20

Closed

Leask mentioned this pull request May 8, 2026

Port Bot API 9.6 support and modernize transport telegraf-hardened/telegraf-hardened#21

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support Bot API 9.6#2092

Support Bot API 9.6#2092
Leask wants to merge 22 commits into
telegraf:v4from
Leask:bot-api-9.6-sync

Leask commented May 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Leask commented May 5, 2026

Uh oh!

siakinnik commented May 7, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Conversation

Leask commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Future direction

Validation

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Leask commented May 5, 2026

Uh oh!

siakinnik commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Leask commented May 5, 2026 •

edited

Loading

siakinnik commented May 7, 2026 •

edited

Loading