@copilotkit/bot-telegram

The Telegram PlatformAdapter for @copilotkit/bot. It connects a Telegram bot to any AG-UI agent: ingress via grammY (long-polling or webhook), egress as Telegram HTML rendered from the @copilotkit/bot-ui JSX vocabulary, plus streaming via chunked message edits, opaque-id interactions, and HITL.

You write your UI as JSX once (@copilotkit/bot-ui) and drive the bot with @copilotkit/bot; this package is the only one that talks to Telegram.

Install

pnpm add @copilotkit/bot-telegram @copilotkit/bot @copilotkit/bot-ui

Quickstart

import { createBot } from "@copilotkit/bot";
import {
  telegram,
  defaultTelegramTools,
  defaultTelegramContext,
} from "@copilotkit/bot-telegram";

const bot = createBot({
  adapters: [
    telegram({
      token: process.env.TELEGRAM_BOT_TOKEN!,
    }),
  ],
  agent: (threadId) => makeAgent(threadId),
  tools: [...defaultTelegramTools, ...appTools], // lookup_telegram_user + your tools
  context: [...defaultTelegramContext, ...appContext], // tagging/HTML/thread guidance
});

bot.onMention(({ thread }) => thread.runAgent());

// Optional: greet users when they start a DM
bot.onThreadStarted(async ({ thread }) => {
  await thread.post(<Message><Section>Hi! How can I help?</Section></Message>);
});

await bot.start();

telegram(opts) returns a TelegramAdapter. By default it runs in long-polling mode — no public URL needed. Set mode: "webhook" (with webhook.domain) to receive updates via HTTP, or mode: "auto" to let the adapter pick based on environment variables (prefers webhook in Vercel/Lambda environments, falls back to polling).

Required env

What it provides

JSX → Telegram HTML rendering + limits

renderTelegram(ir) translates the @copilotkit/bot-ui vocabulary to a Telegram Bot API payload (text, parseMode: "HTML", optional inlineKeyboard, optional photos): Message → container, Header → <b>, Section/Markdown → telegramHtml(), Field(s) → <b>label</b> value, Context → <i>, Actions → inline keyboard rows, Select → inline keyboard rows, Image → photo, Table → <pre> monospace grid, Divider → ──────.

Telegram API limits are enforced via TELEGRAM_LIMITS and the helpers:

Streaming via chunked edits

Replies stream through ChunkedEditStream: the adapter posts a placeholder message and edits it as tokens arrive, throttled to one edit per second. When a reply approaches Telegram's 4 096-char limit (~4 000 characters) the stream transparently mints a second message and continues — keeping each Telegram message within limits with no reflow of already-frozen chunk boundaries.

Interactions (ack-first)

Every Telegram callback_query (inline keyboard button click) is acked promptly via answerCallbackQuery — the adapter's ackDeadlineMs is 3 s so the client spinner clears quickly, well within Telegram's ~30 s validity window for answerCallbackQuery. After acking, decodeInteraction extracts the conversation key and minted opaque id and hands an InteractionEvent to the engine. Unrelated clicks decode to events the bot harmlessly ignores.

HITL via ActionStore

Use thread.awaitChoice(<Picker .../>) to post an interactive inline keyboard and block until a click resolves it; the resolved value is the clicked button's callback data. Agent interrupts (on_interrupt) are captured by the run renderer and dispatched to your onInterrupt handler, which posts a picker; the click resumes the agent via thread.resume(value).

/start → onThreadStarted

The listener intercepts the Telegram /start command in private chats and fires onThreadStarted, letting the bot post a greeting or configure the conversation before the first turn.

Files in/out

Inbound file attachments (photos, audio, video, documents) can be downloaded and delivered to the agent as multimodal AG-UI content parts via buildFileContentParts. The adapter can post files back out via thread.postFile({ bytes, filename }) (sends as a document).

Built-ins

• defaultTelegramTools — ships lookup_telegram_user so the agent can resolve a public @username handle to a Telegram user id for @-mentions. The tool calls getChat with the supplied query and only works for public @username handles; arbitrary display-name queries are not supported and return undefined. Spread into tools.
• defaultTelegramContext — tagging procedure, Markdown-vs-HTML guidance, and the Telegram DM / forum-topic / group-per-user conversation model. Spread into context.

Commands via setMyCommands

registerCommands(specs) calls bot.api.setMyCommands, registering the command menu visible in the Telegram UI. The listener forwards every bot command to the engine's onCommand handlers.

Ingress modes

What's NOT in v1

• Modals / native form submit — Telegram has no modal surface; multi-step forms must be conversation-driven.
• Reactions — Telegram reaction support is not implemented.
• Native streaming — Telegram has no server-push streaming; streaming is approximated via throttled editMessageText calls.
• Durable (Redis/DB) conversation store — TelegramConversationStore is in-memory; sessions and message history are lost on restart.
• Multi-bot install — one bot token per adapter instance.
• <Select> option-value round-trip — Telegram callback_data is limited to 64 bytes. If an option's value or id serializes to more than 64 bytes the renderer silently drops (degrades) that option — the button simply does not appear in the keyboard. Use short id strings on <Option> elements when option values are large objects.

Known limitations

• Group conversation model — in ordinary (non-forum) group chats the bot keys each conversation per-user-per-group (user:<userId>): each member's @mentions form one ongoing conversation for that user, and button clicks resolve to the clicking user's conversation. The bot does not maintain a single shared group thread. Forum supergroups use per-topic threads (topic:<threadId>); DMs are a single flat conversation (dm).
• update() does not change media — editing a previously-posted message via thread.update(ref, ir) calls editMessageText and updates text plus inline keyboard only. Photos attached to the original message are not changed.
• Inbound files — file attachments (photos, audio, video, documents) are downloaded and delivered to the agent as multimodal AG-UI content parts. Large files that exceed Telegram's size cap for getFile are skipped with a note in their place.
• lookup_telegram_user is @username-only — the tool resolves public @username handles by calling getChat. Queries that do not start with @ return undefined immediately; arbitrary display-name or real-name searches are not supported.
• Group HITL (interactive buttons) are per-user — because non-forum group conversations are keyed per sender, an inline-keyboard prompt posted for one user is only resolved when that user clicks it. A different group member clicking the same button is acked but does not resolve the original user's pending choice.
• Concurrency — the in-memory conversation store does not serialize concurrent turns for the same conversation. Rapid back-to-back messages in one conversation may interleave. This is acceptable for typical use; a durable/locking store is out of v1 scope.

Exports

telegram, TelegramAdapter, TelegramAdapterOptions; createRunRenderer, CreateRunRendererArgs; decodeInteraction, conversationKeyOf, deriveConversationKey, toPlatformUser; renderTelegram; TELEGRAM_LIMITS, truncateText, clampArray, byteLen; defaultTelegramTools, lookupTelegramUserTool; defaultTelegramContext, telegramTaggingContext, telegramFormattingContext, telegramConversationModelContext; telegramHtml, escapeHtml; withTelegramFormatFallback, stripHtml; TelegramConversationStore; ChunkedEditStream, ChunkedEditStreamConfig; attachTelegramListener, ListenerConfig; buildFileContentParts, TelegramFileRef, AgentContentPart, FileDeliveryConfig; types: ConversationKey, ReplyTarget, TelegramMessageRef, TelegramInlineButton, TelegramPayload; value DM_SCOPE.