# @frogbotai/piece-telegram-bot 中文文档

规范地址：https://npmcn.com/package/%40frogbotai/piece-telegram-bot/

版本：0\.42\.0
npm 元数据更新时间：2026-11-15T07:38:25.706Z
中文译文更新时间：2026-11-15T14:33:17.800Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40frogbotai/piece-telegram-bot
原文对照：https://npmcn.com/package/%40frogbotai/piece-telegram-bot/?lang=original

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

- 包体积（解压后）：170 kB，79 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：frogbot 0\.42\.0
- 首次发布：2026-07-26T22:22:28.383Z
- 最新版本发布：2026-11-15T07:38:25.520Z
- 近 30 天下载量：2940（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

frogBot的电报机器人工具.

## 安装

```sh
npm install @frogbotai/piece-telegram-bot
```

也可以使用：`pnpm add @frogbotai/piece-telegram-bot`、`yarn add @frogbotai/piece-telegram-bot`、`bun add @frogbotai/piece-telegram-bot`

## README

# `@frogbotai/piece-telegram-bot`

通过FrogBot发送Telegram Bot API请求并接收bot更新.

## 使用量

```ts
import { createTelegramBot } from '@frogbotai/piece-telegram-bot';

export const telegramBot = createTelegramBot({
  auth: { botToken: process.env.TELEGRAM_BOT_TOKEN! },
  webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET!,
  botUsername: 'frogbot',
});
```

## 设置

1.  创建机器人 [瓶装父亲](https://t.me/BotFather) 并复制其机器人标志.
2.  选择只包含字母、数字、下划线或连字符的 Webhook 密钥 。 保持安静.
3.  登记册 `https://<your-host>/api/webhooks/<piece-instance-slug>` 与电报 `setWebhook` 方法并传递与 `secret_token`。 。 。 .
4.  添加 `message`, (中文(简体) ), `edited_message`, (中文(简体) ), `channel_post`, (中文(简体) ), `edited_channel_post`,以及 `callback_query` 改为 `allowed_updates`中添加 `newUpdate`。 。 。 .
5.  当机器人必须收到普通的组信息时,以 BotFather 禁用隐私模式 。 将机器人添加到每个组或频道中,并带有读取和回复所需的权限.
6.  在代理商身上挂载实例 `channels: [telegramBot]` 并明确配置代理服务器 `access` 允许打算匿名的参与者回电.

Telegram不使用webhook挑战握手. 青蛙Bot 验证每一次交货 `X-Telegram-Bot-Api-Secret-Token` 头曰. 设定 `allowedUserIds` 将频道对话限制在已知的Telegram用户ID; 省略或空值允许每个Telegram用户到达bot,但须遵守您青蛙Bot代理访问规则.

允许列表不会认证青蛙Bot 用户 。 Telegram 频道身份总是返回 `null`,因此默认代理访问甚至拒绝允许上市用户. 对于故意的公职人员, `access: () => true` 允许每个代理入境点匿名使用。 对于受限访问,使用检查预定通道和参与者的回调 `req.context.channel`; 保留 `allowedUserIds` 配置为 Telegram 侧过滤器 .

Telegram允许每个瓶子符号一个webhook. 频道适配器和 `newUpdate` 共享上面的实例; 不注册单独的订阅 URL。 直接信息、团体和每个论坛专题仍然是单独的谈话.

启动按钮( E)`/start`),而其他直接消息命令则以命令文本和参数完整地到达代理. 组命令发往 `@<botUsername>` 使用与普通消息相同的引用和对话路由.

## 行动

| 上游动作弹 | 上一个包装导出 | 本地行动 | 页:1 |
| --- | --- | --- | --- |
| `send_text_message` | `sendTextMessage` | `sendTextMessage` |  |
| `send_media` | `sendMedia` | `sendMedia` | 接受一个Telegram文件ID或URL. |
| `send_document` | `sendDocument` | `sendDocument` | 接受一个Telegram文件ID或URL. |
| `send_audio` | `sendAudio` | `sendAudio` | 接受一个Telegram文件ID或URL. |
| `send_location` | `sendLocation` | `sendLocation` |  |
| `send_media_group` | `sendMediaGroup` | `sendMediaGroup` | 接受Telegram文件ID或URL. |
| `send_poll` | `sendPoll` | `sendPoll` |  |
| `send_chat_action` | `sendChatAction` | `sendChatAction` |  |
| `edit_message_text` | `editMessageText` | `editMessageText` |  |
| `delete_message` | `deleteMessage` | `deleteMessage` |  |
| `forward_message` | `forwardMessage` | `forwardMessage` |  |
| `pin_message` | `pinMessage` | `pinMessage` |  |
| `unpin_message` | `unpinMessage` | `unpinMessage` |  |
| `get_chat` | `getChat` | `getChat` |  |
| `get_chat_member` | `getChatMember` | `getChatMember` |  |
| `get_file` | `getFile` | `getFile` | 返回Telegram文件元数据. |
| `create_invite_link` | `createInviteLink` | `createInviteLink` |  |
| `answer_callback_query` | `answerCallbackQuery` | `answerCallbackQuery` |  |
| `custom_api_call` | `customApiCall` | `customApiCall` |  |

## 触发器

| 上游触发弹 | 本地触发 | 类型 | 页:1 |
| --- | --- | --- | --- |
| `new_telegram_message` | `newUpdate` | `app` | 过滤器更新共享频道webhook收到的类型 . |

## 常见问题

### @frogbotai/piece-telegram-bot 是什么？

frogBot的电报机器人工具\.

### 如何安装 @frogbotai/piece-telegram-bot？

在项目目录运行 npm install @frogbotai/piece-telegram-bot，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：frogbot（0\.42\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frogbotai/piece-telegram-bot 支持 TypeScript 吗？

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

### @frogbotai/piece-telegram-bot 支持 ESM 还是 CommonJS？

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

### @frogbotai/piece-telegram-bot 可以商用吗？

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

### @frogbotai/piece-telegram-bot 的下载量有多少？

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

### @frogbotai/piece-telegram-bot 还在维护吗？

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