npm / @chat-adapter/telegram
@chat-adapter/telegram
What changed in @chat-adapter/telegram 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
4 breaking16 new APIs and options1 performance10 behavior and defaults19 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@chat-adapter/telegram 450 changes
Breaking changes 4
Telegram animations are now reported as a single video attachment; the redundant document field is no longer reported as a second attachment.
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.
Webhook verification is now required by default, with an explicit opt-in for unverified webhooks.
Switches polling configuration to longPolling.
New APIs and options 16
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.
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.
Native Telegram drafts are opt-in; set this option to true to restore draft previews in private chats.
Adds a configurable streaming edit interval; edits have a 1100ms floor.
Adds outbound-only Vercel Connect authentication while retaining native webhook verification or polling.
An optional Telegram user allowlist can be configured with allowedUserIds.
The protected sleep helper accepts an optional AbortSignal, allowing stopPolling() to interrupt the polling backoff delay immediately.
A comma-separated environment variable can configure an optional Telegram user allowlist.
Telegram media group uploads now support multiple files and attachments.
Adds native rich message formatting and streaming for Telegram Bot API 10.1.
Adds support for routing Telegram bot commands to Chat SDK slash command handlers.
Adapter internals are protected rather than private, allowing consumers to subclass an adapter and override or extend processUpdate behavior.
Supported Node versions are now set in the package engines metadata.
Telegram attachment uploads now support typed attachments.
Exposes adapter.resetWebhook(...) for resetting the webhook.
Adds Telegram adapter runtime modes: auto, webhook, and polling.
Performance 1
Rich and Markdown native draft updates skip unused plain-text conversion; plain-text fallback and final delivery are unchanged.
Behavior and default changes 10
Telegram file downloads now return portable ArrayBuffer data while preserving Buffer support in the shared attachment contract.
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.
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.
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.
Preserves normalized replied-to message context and populates it from Telegram replies.
Incoming Telegram media groups are combined into one message with ordered attachments and the shared caption.
Adds native Telegram private chat draft streaming, with fallback streaming elsewhere.
The adapter now depends on chat as a full dependency rather than an optional dependency.
Parsed messages now convert Telegram message entities to markdown.
Adds table markdown rendering and fully streaming markdown rendering, and improves adapter fallback-render behavior.
Fixes and other changes 19
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.
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.
Telegram polling waits for handlers to settle before advancing update offsets.
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.
A rate-limited final edit is retried once instead of failing the post.
Streaming now respects Telegram streaming rate limits.
Repeated Telegram webhook updates are deduplicated by update ID using the configured state adapter.
Read receipts now target XChat exactly.
Photo attachments are now reported as JPEG.
Normalized attachment metadata now preserves Telegram stable media identifiers, so developers can rely on them when handling attachments.
No longer falsely matches @bot when @bot-dev is mentioned; the same fix applies to the Telegram adapter's isBotMentioned.
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.
Telegram typing actions are sent immediately when private message updates arrive.
Round video messages are now returned as video attachments with width and height set to the clip's length, instead of being silently dropped.
Source maps are disabled in published packages.
Posting messages with a markdown field now sets parse_mode to Markdown, not only for card messages.
Fixes DM replies failing with “chat not found” because the channel ID was double-prefixed.
Makes automatic runtime-mode fallback safer.
Fixes adapter initialization when the chat username is missing.