# What changed in @chat-adapter/telegram

> 50 changes in @chat-adapter/telegram 4 from its official release notes, upgrade guides and advisories: 4 breaking, 16 new APIs and options. Each one cited. Sources checked 2026-10-18. HTML: https://unstale.sh/npm/@chat-adapter/telegram/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @chat-adapter/telegram 4

### Breaking changes

- Telegram animations are now reported as a single video attachment; the redundant document field is no longer reported as a second attachment. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- Telegram attachment downloads now enforce a 25 MB size cap and a 30-second timeout using the Web Fetch API, supporting runtimes such as Cloudflare Workers. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- Webhook verification is now required by default, with an explicit opt-in for unverified webhooks. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- Switches polling configuration to longPolling. (4.16.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.16.0)

### New APIs and options

- Opt in to Telegram Business mode with businessMode: true. The adapter handles business updates and threads, routes commands and deletes, includes business connection IDs in outbound operations, and caches connection state. Reactions on business threads throw NotImplementedError. (4.40.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.40.0)
- When enabled, replies to the bot's own messages report isMention; the option is off by default and is readable from TELEGRAM_MENTION_ON_REPLY. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- Native Telegram drafts are opt-in; set this option to true to restore draft previews in private chats. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Adds a configurable streaming edit interval; edits have a 1100ms floor. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Adds outbound-only Vercel Connect authentication while retaining native webhook verification or polling. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- An optional Telegram user allowlist can be configured with allowedUserIds. (4.35.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.35.0)
- The protected sleep helper accepts an optional AbortSignal, allowing stopPolling() to interrupt the polling backoff delay immediately. (4.35.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.35.0)
- A comma-separated environment variable can configure an optional Telegram user allowlist. (4.35.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.35.0)
- Telegram media group uploads now support multiple files and attachments. (4.34.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.34.0)
- Adds native rich message formatting and streaming for Telegram Bot API 10.1. (4.31.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.31.0)
- Adds support for routing Telegram bot commands to Chat SDK slash command handlers. (4.31.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.31.0)
- Adapter internals are protected rather than private, allowing consumers to subclass an adapter and override or extend processUpdate behavior. (4.29.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.29.0)
- Supported Node versions are now set in the package engines metadata. (4.29.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.29.0)
- Telegram attachment uploads now support typed attachments. (4.29.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.29.0)
- Exposes adapter.resetWebhook(...) for resetting the webhook. (4.16.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.16.0)
- Adds Telegram adapter runtime modes: auto, webhook, and polling. (4.16.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.16.0)

### Performance

- Rich and Markdown native draft updates skip unused plain-text conversion; plain-text fallback and final delivery are unchanged. (4.40.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.40.0)

### Behavior and default changes

- Telegram file downloads now return portable ArrayBuffer data while preserving Buffer support in the shared attachment contract. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- Stickers now report their emoji as text, falling back to the sticker set name and then "sticker", and include an attachment matching their actual format. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- Messages containing locations, venues, contacts, polls, dice, games, invoices or stories now have short literal text descriptions instead of empty text; structured payload remains on the raw message. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- The adapter owns the post-and-edit loop, streams render the same way in every chat type, and edits stay under Telegram's per-chat rate limit. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Preserves normalized replied-to message context and populates it from Telegram replies. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Incoming Telegram media groups are combined into one message with ordered attachments and the shared caption. (4.37.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.37.0)
- Adds native Telegram private chat draft streaming, with fallback streaming elsewhere. (4.30.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.30.0)
- The adapter now depends on chat as a full dependency rather than an optional dependency. (4.21.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.21.0)
- Parsed messages now convert Telegram message entities to markdown. (4.21.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.21.0)
- Adds table markdown rendering and fully streaming markdown rendering, and improves adapter fallback-render behavior. (4.16.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.16.0)

### Fixes and other changes

- In regular supergroups, a reply to the bot counts as a mention when mentionOnReply is enabled; ordinary replies are no longer dropped by the forum-topic exclusion. (4.42.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.42.0)
- Messages and captions that fit the length limit are no longer cut at a backtick inside a link destination; cuts inside links, code spans, or underlines remove the incomplete entity before the ellipsis. (4.41.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.41.0)
- Telegram polling waits for handlers to settle before advancing update offsets. (4.41.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.41.0)
- Thread.reply() now replies to its target using Telegram reply_parameters, with support across message types and fallback behavior when rich-message gateways reject the parameter. (4.39.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.39.0)
- A rate-limited final edit is retried once instead of failing the post. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Streaming now respects Telegram streaming rate limits. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Repeated Telegram webhook updates are deduplicated by update ID using the configured state adapter. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Read receipts now target XChat exactly. (4.38.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.38.0)
- Photo attachments are now reported as JPEG. (4.36.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.36.0)
- Normalized attachment metadata now preserves Telegram stable media identifiers, so developers can rely on them when handling attachments. (4.36.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.36.0)
- No longer falsely matches @bot when @bot-dev is mentioned; the same fix applies to the Telegram adapter's isBotMentioned. (4.34.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.34.0)
- Valid MarkdownV2 link URLs containing raw underscores are no longer truncated at entity-marker characters; hard truncation inside a link URL now trims back to before the link. (4.32.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.32.0)
- Telegram typing actions are sent immediately when private message updates arrive. (4.32.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.32.0)
- Round video messages are now returned as video attachments with width and height set to the clip's length, instead of being silently dropped. (4.29.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.29.0)
- Source maps are disabled in published packages. (4.24.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.24.0)
- Posting messages with a markdown field now sets parse_mode to Markdown, not only for card messages. (4.21.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.21.0)
- Fixes DM replies failing with “chat not found” because the channel ID was double-prefixed. (4.20.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.20.0)
- Makes automatic runtime-mode fallback safer. (4.16.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.16.0)
- Fixes adapter initialization when the chat username is missing. (4.16.0) — [release notes](https://github.com/vercel/chat/releases/tag/%40chat-adapter/telegram%404.16.0)