@ copilotkit/ channels- telegram (英语)

这个 电报 PlatformAdapter 页:1 @copilotkit/channels连接 a 给任何AG-UI代理的Telegram bot:通过grammY(长波波或webhook)入侵, 以 Telegram HTML 从 @copilotkit/channels-ui JSX词汇, 加上通过块状消息编辑的流出,不透明-ID交互,以及HITL.

你曾经将你的UI写成JSX(@copilotkit/channels-ui和驱动机器人与 @copilotkit/channels;这个包是唯一一个和Telegram说话的.

适配器保存着自己的Telegram bot sorders — 在管理路径中 Channel 在副驾驶 Kit 智能配置内运行 CopilotRuntime (免费计划) ),它开始并拥有频道的生命周期. 大楼 在 SDK 原始版本上操作自己的频道运行器也是支持的 路径.

安装

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

快速启动

文件必须是 .tsx ——"TypeScript"中的"JSX"要求"JSX"工厂必须是" 已配置 。 指着它 @copilotkit/channels-ui 在你身边 tsconfig.json数字 :

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@copilotkit/channels-ui"
  }
}

import { createChannel } from "@copilotkit/channels";
import {
  telegram,
  defaultTelegramTools,
  defaultTelegramContext,
} from "@copilotkit/channels-telegram";
import { Message, Section } from "@copilotkit/channels-ui";
import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

const bot = createChannel({
  identifyUser: "platform",
  name: "support-bot", // project-unique Intelligence Channel name
  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>,
  );
});

// The runtime owns the channel's lifecycle — there is no `bot.start()`.
const runtime = new CopilotRuntime({
  intelligence: new CopilotKitIntelligence({
    // apiUrl and wsUrl default to cloud-hosted CopilotKit Intelligence — override
    // both together only for a self-hosted deployment.
    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!, // free tier available
  }),
  channels: [bot],
});

// Creating the listener starts the Channel's connection.
const listener = createCopilotNodeListener({ runtime });
// Optional: await that activation so a broken config fails startup loudly.
await listener.channels.ready(); // listener.channels.stop() tears it down

telegram(opts) 返回 a TelegramAdapter。默认情况下,它会运行于 长波 模式 — 不需要公共 URL 。 设定 mode: "webhook" (与 webhook.domain)通过HTTP接收更新,或 mode: "auto" 让 基于环境变量的适配器选择(在Vercel/Lambda中首选webhook) 环境,回归民意调查).

必需的嵌入

它提供的东西

JSX → Telegram HTML渲染+限制

renderTelegram(ir) 翻译 @copilotkit/channels-ui 词汇到 a Telegram Bot API 有效载荷(text, (中文(简体) ), parseMode: "HTML"选项 inlineKeyboard选项 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 → ──────。 。 。 .

电讯API限制通过 TELEGRAM_LIMITS 援助者们

通过块化编辑流出

通过的答复流 ChunkedEditStream:适配器设置占位符 消息并编辑它作为符号到达,按住每秒一次编辑。 当a 答覆接近 Telegram 的 4 096- Char 限制( ~ 400 000 个字符) 流 透明地薄荷表示第二个信息并继续——保留每个电报 信件在限制范围内,没有已冻结块边界的回流.

互动(相对第一)

每张电报 callback_query (内线键盘按钮点击) 被锁定 快速通过 answerCallbackQuery - 适配器的 - 对 - the 适配器的 ackDeadlineMs 是 3 个sso 客户端旋转器迅速清除, 远远在Telegram ~ 30 s 的有效性之内 窗口 answerCallbackQuery敲门后, decodeInteraction 摘录 谈话的钥匙和不透明的标识 手掌 InteractionEvent 改为 发动机。 无关的点击可解码到bot无害地忽略的事件.

通过 ActionStore 的 HITL

使用 thread.awaitChoice(<Picker .../>) 发布交互式内置键盘 并屏蔽到点击解决为止;解析的数值是点击的按钮的 调用数据。 代理中断( E)on_interrupt) 被运行的渲染器捕获 并发送到您的 onInterrupt 处理器,它会张贴一个拾取器;单击 通过 thread.resume(value)。 。 。 .

/start → onThreadStarted

监听者截取电报 /start 命令在私人聊天和 火灾 onThreadStarted,让机器人张贴问候或配置 第一回合前的谈话.

输入/退出文件

输入文件附件(相片、音频、视频、文档)可下载 并作为多式AG-UI内容部件通过 buildFileContentParts。适配器可以通过 thread.postFile({ bytes, filename }) (作为 document) (中文(简体) ).

内建

• defaultTelegramTools - 船舶 lookup_telegram_user 这样经纪人就可以 解决公众问题 @username 处理到用于@-mentions的Telegram用户代号. 工具调用 getChat 仅供公众使用 @username 控件; 不支持任意显示名称查询 返回未定义。 展开到 tools。 。 。 .
• defaultTelegramContext 标记程序,Markdown-vs-HTML指导,以及 telegram DM / 论坛主题 / 组合用户对话模式。 展开到 context。 。 。 .

通过 setMyCommands

registerCommands(specs) 电话 bot.api.setMyCommands,登记 在Telegram UI中可见命令菜单。 听者把每个机器人都转过来 命令到引擎的 onCommand 管理者.

入侵模式

反应

message_reaction 自动启用更新。 适配器输出 TELEGRAM_ALLOWED_UPDATES (它所订阅的完整更新类型列表)和 把它传给奶奶的长波 start() 电话.

分组聊天 : 机器人必须是一个 管理员 待收款项 message_reaction 事件。 私人聊天和频道工作,没有任何 额外权限.

Webhook 部署 : 将同一列表传递给 setWebhook数字 :

import { TELEGRAM_ALLOWED_UPDATES } from "@copilotkit/channels-telegram";

await bot.api.setWebhook(url, {
  allowed_updates: [...TELEGRAM_ALLOWED_UPDATES],
});

V1里没有什么

• 模块/ 本地形式提交 - Telegram没有模式表面;多步骤 形式必须是对话驱动的. openModal 决定 { ok: false } 打开 这个适配器——发动机把方法关了,因为 supportsModals 实值 false。 。 。 .
• 原生电文 - 电报没有每个用户可见的信息; supportsEphemeral 实值 false启用 thread.postEphemeral(user, ui, { fallbackToDM: true }) 派一个私人的DM作为后盾. 重新编辑需要用户拥有 之前用机器人开始的DM (直接同意至少一条); 如果他们没有的话,DM sendMessage 呼叫会失败 postEphemeral 决定 { ok: false } 而不是扔东西.
• 原生溪流 ——Telegram没有服务器推出流线;流线是 大约通过节奏 editMessageText 打电话.
• 持久( Redis/ DB) 对话存储 —— 说 TelegramConversationStore 实值 in-memory; 重新启动时会话和信件历史丢失.
• 多机器人安装 ——每个适配器实例一个bot令牌.
• <Select> 选项值回转 - 电报 callback_data 有限 到 64 字节。 如果一个选项 value 或者说 id 序列化为64字节以上 渲染器静静地放下( 降级) 该选项—— 按钮只是做 不出现在键盘中。 使用短数 id 字符串在 <Option> 要素 当选项值是大对象时.

已知的限制

• 集体对话模式 ——在普通(非论坛)小组聊天中,bot 每个用户/组的每次对话按键( e)user:<userId>:每个成员的 @mentions为该用户组成一个持续的对话,并点击 解决点击用户的对话。 机器人会的 没有 维护 单个共享组线索。 论坛超群使用每个主题的线程 (单位:千美元)topic:<threadId>); DMs是单一的平面对话(dm) (中文(简体) ).
• update() 不改变媒体 ——编辑一则先前贴出的消息 通过 thread.update(ref, ir) 电话 editMessageText 并更新文本加 只有内置键盘。 原信件所附照片不是 换了.
• 输入文件 文件附件(相片、音频、视频、文件) 下载后作为多式AG-UI内容部件交付代理商. 超过Telegram大小上限的大型文件 getFile 被跳过 代替他们的笔记.
• lookup_telegram_user 实值 @username- 仅限 ——工具解决公有问题 @username 调用控件 getChat。不以 @ 立即返回未定义; 任意显示名称或真名 不支持搜索.
• 组合 HITL( 交互按钮) 是每个用户 - 因为非论坛小组 每个发送者对口按键, 一个内置键盘提示 用户仅在 那个 用户点击它。 一个不同的集团成员 单击同一按钮时已锁定, 但不能解决原用户的 待定.
• 货币 - 内幕谈话店不串行 同时转身进行同样的对话。 快速背对背信息输入 一次谈话可以互通 这可以用于典型用途;a 耐用/锁入店不在v1范围.

出口

telegram, (中文(简体) ), TelegramAdapter, (中文(简体) ), TelegramAdapterOptions· ; createRunRenderer, (中文(简体) ), CreateRunRendererArgs· ; decodeInteraction, (中文(简体) ), conversationKeyOf, (中文(简体) ), deriveConversationKey, (中文(简体) ), toProviderActor· ; 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· ; 类型 : ConversationKey, (中文(简体) ), ReplyTarget, (中文(简体) ), TelegramMessageRef, (中文(简体) ), TelegramInlineButton, (中文(简体) ), TelegramPayload; 数值 DM_SCOPE。 。 。 .