# @chat-adapter/telegram 中文文档

规范地址：https://npmcn.com/package/%40chat-adapter/telegram/

版本：4\.44\.0
npm 元数据更新时间：2026-11-02T14:55:52.023Z
中文译文更新时间：2026-11-09T11:13:47.908Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chat-adapter/telegram
原文对照：https://npmcn.com/package/%40chat-adapter/telegram/?lang=original
项目主页：https://chat-sdk.dev/adapters/official/telegram
源码仓库：https://github.com/vercel/chat

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：210 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-02-26T23:12:31.048Z
- 最新版本发布：2026-11-02T14:55:51.501Z
- 近 30 天下载量：1530979（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

Chat SDK的电报适配器——Bot API webhooks,内置键盘,反应和流出

## 安装

```sh
npm install @chat-adapter/telegram
```

也可以使用：`pnpm add @chat-adapter/telegram`、`yarn add @chat-adapter/telegram`、`bun add @chat-adapter/telegram`

## README

[![Telegram adapter for Chat SDK](https://chat-sdk.dev/en/adapters/official/telegram/og)](https://chat-sdk.dev/adapters/official/telegram)

# @chat-adapter/ 电报

> npm 软件包 : [`@chat-adapter/telegram`](https://www.npmjs.com/package/@chat-adapter/telegram)

[![Agent Stack](https://img.shields.io/badge/Agent%20Stack-000?style=flat-square&logo=vercel&logoColor=FFF&labelColor=000&color=000)](https://vercel.com/kb/agent-stack) [![MIT License](https://img.shields.io/badge/License-MIT-000?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=000&color=000)](https://npmcn.com/package/LICENSE)

用于 [聊天SDK](https://chat-sdk.dev/)。配置 bot webhoks 和信件.

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

## 安装

```bash
pnpm add @chat-adapter/telegram
```

## 带CLI的脚手架

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

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

访问 [适配器目录](https://chat-sdk.dev/adapters) 见其他官方和供应商官方适配器.

## 快开始

管理下的全权证书见 [**Vercel 连接**](https://npmcn.com/package/%40chat-adapter/telegram/#readme-option-a--vercel-connect)。 。 。 .

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

```typescript
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` 仅是配置,没有环境变量.

| 选项 | 需求 | 说明 |
| --- | --- | --- |
| `allowUnverifiedWebhooks` | 没有 | 接受不进行秘密调试的网络浏览请求 。 自动从 `TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS=true`。仅用于本地开发或信任的验证代理 |
| `allowedUserIds` | 没有 | Telegram用户ID允许触发适配器. 自动从 `TELEGRAM_ALLOWED_USER_IDS` (相相分会. 在省略或空出时允许所有用户 |
| `botToken` | 无\* | Telegram bot 代号. 自动从 `TELEGRAM_BOT_TOKEN` |
| `secretToken` | 网 址 \* | Webhook 暗号. 自动从 `TELEGRAM_WEBHOOK_SECRET_TOKEN` |
| `mode` | 没有 | 适配器模式 : `auto` (违约), `webhook`,或 `polling` |
| `longPolling` | 没有 | 可选长选票配置 `getUpdates` (单位:千美元)`timeout`, (中文(简体) ), `limit`, (中文(简体) ), `allowedUpdates`, (中文(简体) ), `deleteWebhook`, (中文(简体) ), `dropPendingUpdates`, (中文(简体) ), `retryDelayMs`(中文(简体) ) |
| `businessMode` | 没有 | 启用Telegram 业务模式( E)`business_connection`, (中文(简体) ), `business_message`, (中文(简体) ), `edited_business_message`) (中文(简体) ). 默认为 `false` |
| `userName` | 没有 | 用于提及检测的 Bot 用户名 。 自动从 `TELEGRAM_BOT_USERNAME` 或者说 `getMe` |
| `mentionOnReply` | 没有 | 把对机器人自己信息的答复当作一个提示,所以它会通向 `onNewMention`默认为 `false`自动从 `TELEGRAM_MENTION_ON_REPLY=true`. 隐含的论坛专题答复和机器人自己的信息永远不会被计算在内 |
| `nativeStreaming` | 没有 | 在私人聊天中流出Telegram的本土草稿预览. 默认为 `false`,它在每个聊天类型中使用后编辑 |
| `persistThreadHistory` | 没有 | 在 Chat 状态适配器中保存收到的消息和机器人自己的文章 `thread.messages` 财务报告和审定财务报表 `channel.messages` 返回较早的转弯。 默认为 `true`。Telegram没有用于读取聊天历史的Bot API,因此 `false` 处理器只看到在当前进程中缓存的信件 。 当你的应用程序保存自己的笔录时,就关掉 |
| `streamingEditIntervalMs` | 没有 | 编辑后流出路径的最小间隔 。 默认为 `1100` 私下聊天和 `3100` 并担任聊天层的一层 `streamingUpdateIntervalMs` |
| `longMessages` | 没有 | 如何发送超过Telegram信件限制的文本帖: `truncate` 以椭圆切除它们, `split` 将全文作为连续信件发送。 见 [长消息](https://npmcn.com/package/%40chat-adapter/telegram/#readme-long-messages) |
| `apiUrl` | 没有 | Telegram API 基础 URL. 自动从 `TELEGRAM_API_BASE_URL`启用 `apiUrl` 用于交叉适应的一致性;遗留问题 `apiBaseUrl` 仍然接受别名 |
| `logger` | 没有 | 锁定实例( 默认为 `ConsoleLogger("info")`(中文(简体) ) |

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

## 认证

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

### 选项A——Vercel连接

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

```typescript
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——瓶子代号

通过 [瓶装父亲](https://t.me/BotFather) 并直接向适配者提供其标志:

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

## Webhook 路线

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


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

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

```bash
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业务模式 :

```typescript
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会重新使用任何早期的调用集列表,这可以默默地排除业务更新. 在您自己注册网页时, 包含业务更新类型 :

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

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

默认为 `false` 用于向后兼容.

## 投票(地方发展)

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

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

```typescript
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),它会自动回归投票.

```typescript
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等运行时间持续工作.

## 环境变量

```bash
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` 仅用于本地开发,或当一个值得信赖的上游验证每项请求才到达适配器.

## 特征

### 通讯

| 特性 | 支助 |
| --- | --- |
| 邮件 | 对 |
| 编辑信件 | 对 |
| 删除信件 | 对 |
| 文件上传 | 对(`sendDocument`, (中文(简体) ), `sendMediaGroup`(中文(简体) ) |
| 附件上传 | 对(`sendPhoto`, (中文(简体) ), `sendAudio`, (中文(简体) ), `sendVideo`, (中文(简体) ), `sendDocument`, (中文(简体) ), `sendMediaGroup`(中文(简体) ) |
| 流线 | 后/编辑 + 选入私人聊天 内容丰富的草稿 |

### 丰富内容

| 特性 | 支助 |
| --- | --- |
| 卡片格式 | 标记下V2 + 内置键盘按钮 |
| 按钮 | 内置键盘回调 |
| 链接按钮 | 内置键盘 URL |
| 选择菜单 | 没有 |
| 表格 | 对下标和 AST 消息的原生, ASCII 在卡片中 |
| 字段 | 对 |
| 纸牌中的图像 | 没有 |
| 模块 | 没有 |

### 对话

| 特性 | 支助 |
| --- | --- |
| 斜线命令 | 没有 |
| 提及 | 对 |
| 添加反应 | 对 |
| 删除反应 | 对 |
| 打字指标 | 对 |
| 模式 | 对 |
| 电文 | 没有 |

### 信件历史

| 特性 | 支助 |
| --- | --- |
| 获取信件 | 缓存 |
| 获取单个消息 | 缓存 |
| 获取线索信息 | 对 |
| 获取频道消息 | 缓存 |
| 列表线索 | 没有 |
| 获取频道信息 | 对 |
| 后频道消息 | 对 |

## 流线

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

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

[Telegram 客户端应删除预览草稿](https://core.telegram.org/api/bots/ai#live-response-streaming) 当最终消息到达时,但草稿渲染因客户端而异. 当您的机器人必须在Telegram客户端中一致工作时, 请保持默认值 .

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

```typescript
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"` 将全文作为连续信件发送,每封都在限制范围内:

```typescript
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, 适配器模式, 以及项目常规 .

```bash
npx skills add vercel/chat
```

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

您也可以安装 [Vercel 插件](https://vercel.com/docs/agent-resources/vercel-plugin) 包括Chat SDK技术与专家代理、代理斜线指令

```bash
npx plugins add vercel/vercel-plugin
```

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

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

## 许可证

麻省理工学院

## 常见问题

### @chat-adapter/telegram 是什么？

Chat SDK的电报适配器——Bot API webhooks,内置键盘,反应和流出

### 如何安装 @chat-adapter/telegram？

在项目目录运行 npm install @chat-adapter/telegram，或使用 pnpm add / yarn add / bun add。

### @chat-adapter/telegram 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @chat-adapter/telegram 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chat-adapter/telegram 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chat-adapter/telegram 可以商用吗？

@chat-adapter/telegram 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chat-adapter/telegram 的下载量有多少？

根据 npm 官方下载统计，@chat-adapter/telegram 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,530,979 次，日均约 51,033 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chat-adapter/telegram 还在维护吗？

最新版本 4\.44\.0 发布于 2026/11/02（6 天前）；至今共发布 35 个版本，其中过去 12 个月发布了 35 个；首次发布于 2026/02/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。