package
Telegram adapter for Chat SDK — Bot API webhooks, inline keyboards, reactions, and streaming
npm install @chat-adapter/telegramGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
Telegram adapter for Chat SDK. Configure for bot webhooks and messaging.
Documentation: chat-sdk.dev/adapters/official/telegram · Guides: vercel.com/kb/chat-sdk
pnpm add @chat-adapter/telegramTo scaffold a new Telegram bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter telegram memoryVisit the adapters directory to see other available official and vendor-official adapters.
For managed credentials, see Vercel Connect.
The adapter auto-detects TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET_TOKEN, TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS, TELEGRAM_BOT_USERNAME, TELEGRAM_MENTION_ON_REPLY, and TELEGRAM_API_BASE_URL from environment variables:
import { Chat } from "chat";
import { createTelegramAdapter } from "@chat-adapter/telegram";
const bot = new Chat({
userName: "mybot",
adapters: {
telegram: createTelegramAdapter(),
},
});
bot.onNewMention(async (thread, message) => {
await thread.post(`You said: ${message.text}`);
});Most options are auto-detected from environment variables when not provided. nativeStreaming, persistThreadHistory, streamingEditIntervalMs, and longMessages are config only and have no environment variables.
| Option | Required | Description |
|---|---|---|
allowUnverifiedWebhooks | No | Accept webhook requests without secret-token verification. Auto-detected from TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS=true. Use only for local development or behind a trusted verifying proxy |
allowedUserIds | No | Telegram user IDs allowed to trigger the adapter. Auto-detected from TELEGRAM_ALLOWED_USER_IDS (comma-separated). All users are allowed when omitted or empty |
botToken | No* | Telegram bot token. Auto-detected from TELEGRAM_BOT_TOKEN |
secretToken | Webhook* | Webhook secret token. Auto-detected from TELEGRAM_WEBHOOK_SECRET_TOKEN |
mode | No | Adapter mode: auto (default), webhook, or polling |
longPolling | No | Optional long polling config for getUpdates (timeout, limit, allowedUpdates, deleteWebhook, dropPendingUpdates, retryDelayMs) |
businessMode | No | Enable Telegram Business mode (business_connection, business_message, edited_business_message). Defaults to false |
userName | No | Bot username used for mention detection. Auto-detected from TELEGRAM_BOT_USERNAME or getMe |
mentionOnReply | No | Treat a reply to one of the bot's own messages as a mention, so it routes to onNewMention. Defaults to false. Auto-detected from TELEGRAM_MENTION_ON_REPLY=true. Implicit forum-topic replies and the bot's own messages never count |
nativeStreaming | No | Stream with Telegram's native draft previews in private chats. Defaults to false, which uses post-and-edit in every chat type |
persistThreadHistory | No | Save incoming messages and the bot's own posts in the Chat state adapter so thread.messages and channel.messages return earlier turns. Defaults to true. Telegram has no Bot API for reading chat history, so with false handlers see only messages cached in the current process. Turn it off when your app keeps its own transcript |
streamingEditIntervalMs | No | Minimum interval between edits on the post-and-edit streaming path. Defaults to 1100 in private chats and 3100 in other chats, and acts as a floor for the Chat-level streamingUpdateIntervalMs |
longMessages | No | How text posts longer than Telegram's message limit are sent: truncate (default) cuts them with an ellipsis, split sends the full text as consecutive messages. See Long messages |
apiUrl | No | Telegram API base URL. Auto-detected from TELEGRAM_API_BASE_URL. Use apiUrl for cross-adapter consistency; the legacy apiBaseUrl alias is still accepted |
logger | No | Logger instance (defaults to ConsoleLogger("info")) |
*botToken is always required. Webhook mode also requires secretToken unless allowUnverifiedWebhooks is explicitly enabled. Polling mode does not require webhook verification.
Use Vercel Connect to manage the outbound bot token, or provide the token directly. Both options use Telegram's native webhook verification; polling does not require a webhook secret.
Use connectTelegramAdapter to resolve the outbound bot token from Vercel
Connect:
import { createTelegramAdapter } from "@chat-adapter/telegram";
import { connectTelegramAdapter } from "@vercel/connect/chat";
const telegram = createTelegramAdapter({
...connectTelegramAdapter("telegram/acme-telegram"),
secretToken: process.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
});Connect does not forward Telegram webhooks. Keep
TELEGRAM_WEBHOOK_SECRET_TOKEN when using webhook mode, or use polling mode
without an inbound webhook. TELEGRAM_BOT_TOKEN is not needed when using the
Connect helper. The adapter derives webhook deduplication scope from Telegram's
stable bot identity, so token rotation does not split update claims. If bot
identity lookup fails at startup, the next accepted webhook retries it.
Create a bot via BotFather and provide its token directly to the adapter:
/newbot and follow the prompts.TELEGRAM_BOT_TOKEN.TELEGRAM_BOT_USERNAME.import { bot } from "@/lib/bot";
export async function POST(request: Request): Promise<Response> {
return bot.webhooks.telegram(request);
}Configure this URL as your bot webhook in BotFather / Telegram API:
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/api/webhooks/telegram",
"secret_token": "your-secret-token"
}'Enable Telegram Business mode when your bot manages customer conversations on behalf of a connected business account:
const telegram = createTelegramAdapter({
businessMode: true,
});With businessMode: true, the adapter:
business_connection, business_message, and edited_business_message updatessender_business_bot), and connections without can_replytelegram:biz:{connectionId}:{chatId}. Each business conversation is its own channel, kept apart from any direct chat the same customer has with the botbusiness_connection_id on outbound sendMessage, edits, typing, file uploads, and on threads created from inline-keyboard callbacks/commands from business chats through onSlashCommand, the same as regular chatsdeleteBusinessMessages, which needs the can_delete_sent_messages right on the connectionReactions are not available on business threads. The Bot API has no business variant of setMessageReaction, so addReaction and removeReaction throw a NotImplementedError there.
When polling, the adapter always sends an explicit allowed_updates list in Business mode: the default update types plus the business ones, or your longPolling.allowedUpdates merged with the business ones. Telegram otherwise reuses whatever list an earlier call set, which can silently exclude business updates. When registering a webhook yourself, include the business update types:
[
"message",
"business_connection",
"business_message",
"edited_business_message"
]Business thread IDs start with telegram:biz, so state adapters that shard by the first two ID segments (such as Cloudflare Agents) place every business conversation in one shard. Override the sharder with a key that includes the connection ID if that matters for your deployment.
Defaults to false for backward compatibility.
When developing locally you typically can't expose a public URL for Telegram to deliver webhooks to. Polling mode uses getUpdates to fetch messages directly from Telegram instead — no public endpoint needed.
The longPolling option is entirely optional. Sensible defaults are applied when omitted.
import { Chat } from "chat";
import { createTelegramAdapter } from "@chat-adapter/telegram";
import { createMemoryState } from "@chat-adapter/state-memory";
const telegram = createTelegramAdapter({
mode: "polling",
// Optional — fine-tune polling behavior:
// longPolling: { timeout: 30, dropPendingUpdates: false },
});
const bot = new Chat({
userName: "mybot",
adapters: { telegram },
state: createMemoryState(),
});
// Optional manual lifecycle control:
// await telegram.resetWebhook();
// await telegram.startPolling();
// await telegram.stopPolling();Each getUpdates request has a deadline of the long polling timeout plus 30 seconds, and the getMe and deleteWebhook requests have a 30 second deadline. If a connection drops without a reset, the request fails at the deadline, the adapter logs a Telegram polling request failed warning with Telegram getUpdates request timed out in its error field, and polling resumes on a new connection after a backoff.
With mode: "auto" (the default), the adapter picks the right strategy for you. When deployed to a serverless environment like Vercel it uses webhooks; everywhere else (e.g. local dev) it falls back to polling automatically.
import { Chat } from "chat";
import { createTelegramAdapter } from "@chat-adapter/telegram";
import { createMemoryState } from "@chat-adapter/state-memory";
const telegram = createTelegramAdapter({
mode: "auto", // default
});
export const bot = new Chat({
userName: "mybot",
adapters: { telegram },
state: createMemoryState(),
});
// Call initialize() so polling can start in long-running local processes:
void bot.initialize();
console.log(telegram.runtimeMode); // "webhook" | "polling"Incoming file attachments expose a lazy fetchData() served from the configured Bot API host. Downloads are limited to 25 MB and time out after 30 seconds. They use the Web Fetch API, so file downloads keep working in runtimes like Cloudflare Workers.
TELEGRAM_ALLOWED_USER_IDS=123456789,987654321
TELEGRAM_BOT_TOKEN=123456:ABCDEF...
TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret
TELEGRAM_BOT_USERNAME=mybot
# Optional (treat replies to the bot as mentions)
TELEGRAM_MENTION_ON_REPLY=true
# Optional (self-hosted API gateway)
TELEGRAM_API_BASE_URL=https://api.telegram.orgSet TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS=true only for local development or when a trusted upstream verifies every request before it reaches the adapter.
| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | Yes |
| Delete message | Yes |
| File uploads | Yes (sendDocument, sendMediaGroup) |
| Attachment uploads | Yes (sendPhoto, sendAudio, sendVideo, sendDocument, sendMediaGroup) |
| Streaming | Post/edit + opt-in private chat rich drafts |
| Feature | Supported |
|---|---|
| Card format | MarkdownV2 + inline keyboard buttons |
| Buttons | Inline keyboard callbacks |
| Link buttons | Inline keyboard URLs |
| Select menus | No |
| Tables | Native for markdown and AST messages, ASCII in cards |
| Fields | Yes |
| Images in cards | No |
| Modals | No |
| Feature | Supported |
|---|---|
| Slash commands | No |
| Mentions | Yes |
| Add reactions | Yes |
| Remove reactions | Yes |
| Typing indicator | Yes |
| DMs | Yes |
| Ephemeral messages | No |
| Feature | Supported |
|---|---|
| Fetch messages | Cached |
| Fetch single message | Cached |
| Fetch thread info | Yes |
| Fetch channel messages | Cached |
| List threads | No |
| Fetch channel info | Yes |
| Post channel message | Yes |
Streams use post-and-edit by default for consistent behavior across Telegram clients. To opt into native draft previews in private chats:
const telegram = createTelegramAdapter({ nativeStreaming: true });Telegram clients should dismiss a draft preview when the final message arrives, but draft rendering varies between clients. Keep the default when your bot must work consistently across Telegram clients.
Telegram recommends at most one message per second in a single chat and limits groups to 20 messages per minute. Sends and edits share flood control, so the post-and-edit path defaults to 1100ms between operations in private chats and 3100ms in other chats. This is a floor: a lower streamingUpdateIntervalMs on your Chat instance does not push the adapter past it. Override it with streamingEditIntervalMs:
const telegram = createTelegramAdapter({ streamingEditIntervalMs: 4000 });If Telegram rate limits the final edit, the adapter waits and retries when the requested delay is 5 seconds or less. Longer delays and failed retries reject the post so it never reports text that Telegram did not receive.
On Telegram Bot API 10.1 and newer, explicit { markdown } and { ast } messages use rich messages, including native headings, lists, tables, task lists, formulas, details, and separate media blocks supported by the Bot API.
Plain strings, raw messages, cards, and media captions retain their existing lightweight message paths. Cards and captions use Telegram's MarkdownV2 parse mode with context-aware escaping. If an older or custom Bot API server does not support rich message methods, the adapter automatically falls back to the existing MarkdownV2 path.
Behavior change in 4.27.0: previous versions used Telegram's legacy Markdown parse mode, which used different syntax (*bold* instead of **bold**) and silently rejected any text containing unescaped ., !, (, ), -, _. If you were emitting raw legacy-Markdown strings or hand-escaping characters yourself, drop the manual escaping. The renderer does it for you. Pass { raw: "..." } only if you need to ship a fully pre-escaped MarkdownV2 string.
Telegram limits a message to 4,096 characters, or 32,768 for rich messages. By default, the adapter truncates longer text posts and ends them with an ellipsis. MarkdownV2 escaping counts toward the limit, so heavily punctuated markdown is cut earlier than its source length suggests.
Set longMessages: "split" to send the full text as consecutive messages, each within the limit:
const telegram = createTelegramAdapter({ longMessages: "split" });The adapter splits between blocks where possible, then at line breaks or spaces, and reopens formatting in the next message. Split tables repeat their header row when it fits beside a body row. Only the first message replies to the original message, and post() returns the last message. Cards, media captions, edits, and the message edited during post-and-edit streaming still truncate.
The adapter waits about 1 second between messages in private chats and about 3 seconds in groups and channels, so a 40-message group post takes about two minutes. Once the first message is delivered, a rate-limited message is sent again after Telegram's retry_after period, up to three attempts. If a wait would be longer than 30 seconds, all three attempts are rate limited, or the waits for one post would add up to more than 60 seconds, post() throws an AdapterRateLimitError and the messages already sent stay in the chat. A rate limit on the first message throws right away, before anything is sent.
update_id are deduplicated for 24 hours through the configured state adapter. Use shared durable state across serverless instances. If state is unavailable, the adapter returns 503 so Telegram retries without dispatching.secretToken unless allowUnverifiedWebhooks is explicitly enabled. Polling mode does not require webhook verification.fetchMessages / fetchChannelMessages return adapter-cached messages from the current process.listThreads is not available for Telegram chats.mode: "polling" deletes webhook by default before calling getUpdates.mode: "auto" checks getWebhookInfo: if a webhook URL exists it uses webhook mode; if it is empty it falls back to polling on non-serverless runtimes without deleting webhook.getWebhookInfo fails in mode: "auto", the adapter stays in webhook mode (safe fallback).Button and LinkButton in card Actions render as inline keyboard buttons. An Actions block with more than 8 buttons wraps into evenly sized rows of at most 8, because Telegram keeps only the first 8 buttons of a row and drops the rest.id/value payloads short.file_id and stable file_unique_id as fetchMetadata.fileId and fetchMetadata.fileUniqueId. Photo attachments use the image/jpeg MIME type.files upload as Telegram documents. Multiple files are sent as Telegram media groups. attachments preserve image, audio, video, or file media type and also use media groups when multiple compatible attachments are posted. Use data or fetchData for private/authenticated files; URL-only attachments must be public URLs Telegram can fetch directly.If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chatThe skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 24 packages.
2.5 MB
Includes dependencies.