@chat-adapter/ 电报

npm 软件包 : @chat-adapter/telegram

用于 聊天SDK。配置 bot webhoks 和信件.

联合国 聊天-sdk.dev/适应者/官方/电报 指南: vercel.com/kb/chat-sdk (英语)

安装

pnpm add @chat-adapter/telegram

带CLI的脚手架

要用这个适配器预选的新Telegram机器人脚手架:

npx create-chat-sdk@latest my-bot --adapter telegram memory

访问 适配器目录 见其他官方和供应商官方适配器.

快开始

管理下的全权证书见 Vercel 连接。 。 。 .

适配器自动检测器 TELEGRAM_BOT_TOKEN, (中文(简体) ), TELEGRAM_WEBHOOK_SECRET_TOKEN, (中文(简体) ), TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS, (中文(简体) ), TELEGRAM_BOT_USERNAME, (中文(简体) ), TELEGRAM_MENTION_ON_REPLY,以及 TELEGRAM_API_BASE_URL 从环境变量:

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}`);
});

配置

大多数选项在未提供时会从环境变量中自动检测出. nativeStreaming, (中文(简体) ), persistThreadHistory, (中文(简体) ), streamingEditIntervalMs,以及 longMessages 仅是配置,没有环境变量.

* 联合国botToken 总是需要。 Webhook 模式也要求 secretToken 除非 allowUnverifiedWebhooks 已明确启用。 投票模式不需要网络hook验证.

认证

使用Vercel Connect来管理出界的bot令牌,或者直接提供令牌. 两个选项都使用Telegram的本土网络hook验证;投票不需要网络hook的秘密.

选项A——Vercel连接

使用 connectTelegramAdapter 解决来自Vercel的外出机器人符号 连接 :

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,
});

连接不转发 Telegram webhooks 。 保留 TELEGRAM_WEBHOOK_SECRET_TOKEN 使用 webhook 模式时,或使用投票模式时 没有进入的网路. TELEGRAM_BOT_TOKEN 在使用时不需要 连接帮助者. 适配器来自Telegram的 Webhook 分解范围 稳定的机器人身份,所以符号旋转不会分割更新索赔. 如果机器人 身份搜索在启动时失败, 下一个被接受的 webhook 重试它 .

备选案文B——瓶子代号

通过 瓶装父亲 并直接向适配者提供其标志:

1. 发送 /newbot 并遵守命令.
2. 复制令牌到 TELEGRAM_BOT_TOKEN。 。 。 .
3. 可选选择用户名并复制到 TELEGRAM_BOT_USERNAME。 。 。 .

Webhook 路线

import { bot } from "@/lib/bot";


export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.telegram(request);
}

配置此 URL 为您在 BotFather / Telegram API 中的 bot webhook :

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"
  }'

业务模式( 连接商务箱)

当您的机器人代表连接的商业账户管理客户对话时, 启用Telegram业务模式 :

const telegram = createTelegramAdapter({
  businessMode: true,
});

与 businessMode: true,适配器:

• 处理 business_connection, (中文(简体) ), business_message,以及 edited_business_message 更新
• 跳过由企业主输入的信息, 代表账户发送的bot 本身的信息( )sender_business_bot),和无连接 can_reply
• 将业务线索编码为 telegram:biz:{connectionId}:{chatId}。每个商业对话都是自己的渠道, 与同一个客户与机器人直接交谈无关
• 通行证 business_connection_id 外出时 sendMessage,编辑,打字,文件上传,以及在由内线键盘回调创建的线程上
• 路线 /commands 从商务聊天到 onSlashCommand,与常规聊天相同
• 删除信件为 deleteBusinessMessages,则需要 can_delete_sent_messages 连接右侧
• 在 Chat SDK 状态适配器中存储连接状态, 因此每个运行实例都会遵守已取消或已禁用的连接

业务线索上没有反应. Bot API 没有商业变体 setMessageReaction这样 addReaction 财务报告和审定财务报表 removeReaction 丢出一个 NotImplementedError 在这里.

当投票时,适配器总是发出一个明确的 allowed_updates 在商务模式下列表:默认更新类型加商务类型,或您的 longPolling.allowedUpdates 与企业合并。 否则Telegram会重新使用任何早期的调用集列表,这可以默默地排除业务更新. 在您自己注册网页时, 包含业务更新类型 :

[
  "message",
  "business_connection",
  "business_message",
  "edited_business_message"
]

商业线程 ID 起始 telegram:biz,因此,状态适配器被前两个ID段(如Cloudflare Agents)所硬化,将每个业务对话都放在一个硬板上. 使用包含连接ID的密钥覆盖硬盘, 如果这对您的部署很重要的话 .

默认为 false 用于向后兼容.

投票(地方发展)

当本地开发时, 您通常无法打开一个 Telegram 的 公共 URL 来传送网络用户 。 投票模式的使用 getUpdates 直接从Telegram获取消息——不需要公共端点.

这个 longPolling 选项是完全可选的。 省略时适用感知默认.

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();

自动模式

与 mode: "auto" 适配器为您选择正确的策略。 当部署到像Vercel这样的没有服务器的环境时,它使用webhooks;在其它任何地方(如:local dev),它会自动回归投票.

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"

入境附件

来袭文件附件暴露出懒惰者 fetchData() 从配置的 Bot API 主机服务 。 下载限制为25 MB,30秒后暂停. 他们使用"Web Fettle"API,因此文件下载在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.org

设定 TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS=true 仅用于本地开发,或当一个值得信赖的上游验证每项请求才到达适配器.

特征

通讯

丰富内容

对话

信件历史

流线

Streams默认使用后版并进行编辑,用于整个Telegram客户端的一致行为. 在私人聊天中选择本地草稿预览 :

const telegram = createTelegramAdapter({ nativeStreaming: true });

Telegram 客户端应删除预览草稿 当最终消息到达时,但草稿渲染因客户端而异. 当您的机器人必须在Telegram客户端中一致工作时, 请保持默认值 .

Telegram在一次聊天中最多建议每秒一个消息,并将分组限制在每分钟20个消息. 发送和编辑共享洪灾控制,因此后编辑路径默认在私人聊天的操作和在其他聊天的3100m之间的操作之间为1100ms. 这是一层:下一层 streamingUpdateIntervalMs 在你身边 Chat 实例不会推动适配器通过它。 用它来代替它 streamingEditIntervalMs数字 :

const telegram = createTelegramAdapter({ streamingEditIntervalMs: 4000 });

如果Telegram率限制最终编辑,适配器在请求的延迟为5秒或更短时会等待并重试. 更长时间的延迟和失败的重试拒绝了该帖子,因此它从来没有报告Telegram没有收到的文本.

下调格式

在Telegram Bot API 10.1和较新的,明确 { markdown } 财务报告和审定财务报表 { ast } 消息使用丰富的消息,包括本地标题,列表,表格,任务列表,公式,细节,以及由Bot API支持的单独的媒体块.

平面字符串、原始消息、卡片和媒体标题保留现有的轻量级消息路径。 卡片和标题使用Telegram的 MarkdownV2 解析模式, 并带有上下文意识 。 如果一个更古老或自定义的Bot API服务器不支持丰富的消息方法,适配器会自动倒回现有的MarkdownV2路径.

4.27.0中的行为变化:前版本使用Telegram的遗作 Markdown 解析模式,它使用不同的语法(*bold* 改为 **bold**)并默地拒绝任何包含未脱逃内容的文本 ., (中文(简体) ), !, (中文(简体) ), (, (中文(简体) ), ), (中文(简体) ), -, (中文(简体) ), _。如果您自己释放原始的遗物- Markdown 字符串或手取名符号, 请放弃手取名符。 造物师为你做。 过 { raw: "..." } 只有当您需要发送一个预留的 MarkdownV2 字符串时.

长消息

Telegram将消息限制在4,096个字符,或32,768个丰富的消息. 默认情况下,适配器会缩短较长的文本帖子并用椭圆来结束. MarkdownV2逃出计数到极限,所以猛烈地打出分数的分数被砍得比其源长度所暗示的要早.

设定 longMessages: "split" 将全文作为连续信件发送,每封都在限制范围内:

const telegram = createTelegramAdapter({ longMessages: "split" });

适配器尽可能在区块之间分出,然后在换行或空格时再在下一封信中重开格式。 分开的表格重复他们的标题行,当它适合身体行。 只有第一个信息回复了原始信息,并且 post() 返回最后一个消息。 卡片,媒体字幕,编辑,以及编辑后流出时所编辑的信息仍然被截取.

适配器在私下聊天的留言间等了约一秒,在组和频道等了约三秒,因此一个40个消息组的帖子大约需要两分钟. 一旦第一个消息被发送,在Telegram之后会再次发送一个速率有限的消息 retry_after 最多三次尝试 如果等待时间超过30秒,所有三次尝试都受速率限制,或者等待一个职位的时间加起来超过60秒, post() 丢出一个 AdapterRateLimitError 和已经发送的消息留在聊天中 。 首个信件的速率限制在发送任何信息之前立即丢出.

页:1

• 以整数接受 Webhook 更新 update_id 通过已配置的状态适配器,复制24小时。 在没有服务器的情况下使用共享持久状态 。 如果状态不可用,适配器返回503,所以Telegram重试时不发送.
• 需要 Webhook 模式 secretToken 除非 allowUnverifiedWebhooks 已明确启用。 投票模式不需要网络hook验证.
• Telegram不会将完整的历史消息API暴露给bots. fetchMessages 编号 : fetchChannelMessages 从当前进程返回适配器标记的信息.
• listThreads 无法进行Telegram聊天.
• 投票和网络呼喊在Telegram中是相互排斥的.
• mode: "polling" 在调用前默认删除 webhook getUpdates。 。 。 .
• mode: "auto" 检查 getWebhookInfo:如果一个webhook URL存在,它使用webhook模式;如果它是空的,它会回到非服务器运行时间的投票,而不删除webhook.
• 若为 getWebhookInfo 失败 mode: "auto",适配器会保持webhook模式(安全倒置).
• Button 财务报告和审定财务报表 LinkButton 纸牌 Actions 转换为内置键盘按钮.
• Telegram回调数据仅限于64字节. 保持按钮 id编号 :value 载荷短.
• 来信附件保存Telegram的可下载性 file_id 稳定 file_unique_id 作为 fetchMetadata.fileId 财务报告和审定财务报表 fetchMetadata.fileUniqueId图片附件使用 image/jpeg MIME类型.
• files 上传为Telegram文档. 多个 files 以Telegram媒体组的形式发送. attachments 保存图像、音频、视频或文件媒体类型,并在张贴多个兼容附件时使用媒体组。 使用 data 或者说 fetchData 用于私有/认证文件; 仅限 URL 的附件必须是公共 URL Telegram 可以直接获取 .
• 其他丰富的卡片元素(图像/选择菜单/radios)仅作回放文本.

AI 编码代理

如果您使用OpenAI Codex, Claude Code, 或 Cursor 等AI编码代理, 在写入代码前安装 Chat SDK 技能, 使其了解 SDK API, 适配器模式, 以及项目常规 .

npx skills add vercel/chat

技术参考文献 node_modules/chat/docs,加上已发布的软件包中的适配器指南和启动模板.

您也可以安装 Vercel 插件 包括Chat SDK技术与专家代理、代理斜线指令

npx plugins add vercel/vercel-plugin

插件是可选的;单是技能就足以用Chat SDK来构建.

关于可代理阅读的文件,见 聊天- sdk.dev/llms.txt (页数索引)或 聊天- sdk.dev/llms- full.txt (全文).

许可证

麻省理工学院