telegram

Telegram

用于 Telegram 机器人并基于 Telegram Bot API（https://api.telegram.org/bot<token>/<method>）的脚本。发送文本、媒体、位置、联系人和投票；编辑、删除、转发、复制和固定消息；并解析机器人交互的聊天、成员和文件。每个脚本都以机器人身份运行——机器人必须是其发送消息的任何聊天的成员，且用户必须先给机器人发消息，机器人才能向其发送私信。

Telegram 的独立非官方连接器。与 Telegram 无关联，未获其认可或赞助。“Telegram”是其所有者的商标，仅用于标识本连接器所适配的服务。

适用场景

• Agent 需要 Telegram 机器人向聊天发送消息、照片、文档、视频、音频、位置、联系人或投票。
• Agent 需要管理机器人发送的消息——编辑、删除、转发、复制、固定或取消固定。
• Agent 需要解析聊天或成员——查找 chat_id（通过 listRecentChats）、确认聊天（getChat）、检查成员的角色（getChatMember）或列出管理员。

设置

这是一个 agentskills.io 技能。

如果尚未将连接器安装为技能，请先使用 npx skills add zapier/connectors --skill telegram 安装（或使用你所用运行环境自身的技能安装机制），然后继续。安装技能只会复制这些文件，不会安装依赖项。在运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。要在自己的项目中将已发布的软件包作为依赖项导入？该 npm install 已会解析所有依赖项——请参阅 references/use-as-sdk.md。

想要获取实际的仓库源代码——浏览 references/、运行此连接器的测试或修改代码？请参阅 README.md，了解如何克隆指定范围的仓库。

此连接器需要 Node.js 22.18+。根据运行方式选择相应的参考文档，并在进行其他操作前先加载：

你拥有……	加载
支持 MCP 的客户端——工具可能已加载（例如 mcp__telegram__<tool>），或者你可以自行注册本地服务（或指导用户注册）	references/use-as-mcp.md
终端／子进程访问权限（可以运行 node）	references/use-as-cli.md
仅有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无工具访问权限、无终端、无法导入此软件包——你需要编写自己的代码，直接调用 Telegram API（例如，在代码执行沙箱中）	references/use-as-recipe.md

脚本

所有脚本都使用单个 telegram 连接。

Script	脚本名称	连接	描述
scripts/sendMessage.ts	sendMessage	单一（telegram）	向聊天发送文本消息。
scripts/sendPhoto.ts	sendPhoto	单一（telegram）	通过 URL 或 file_id 发送照片。
scripts/sendDocument.ts	sendDocument	单一（telegram）	通过 URL 或 file_id 发送文件/文档。
scripts/sendVideo.ts	sendVideo	单一（telegram）	通过 URL 或 file_id 发送视频。
scripts/sendAudio.ts	sendAudio	单一（telegram）	通过 URL 或 file_id 发送音频文件（音乐）。
scripts/sendLocation.ts	sendLocation	单一（telegram）	发送地图上的地点。
scripts/sendContact.ts	sendContact	单一（telegram）	发送联系人电话。
scripts/sendPoll.ts	sendPoll	单一（telegram）	发送投票或测验。
scripts/editMessageText.ts	editMessageText	单一（telegram）	编辑机器人发送的消息文本。
scripts/deleteMessage.ts	deleteMessage	单一（telegram）	删除聊天中的消息。
scripts/forwardMessage.ts	forwardMessage	单一（telegram）	转发消息并保留来源信息。
scripts/copyMessage.ts	copyMessage	单一（telegram）	复制消息内容，但不保留来源信息。
scripts/pinChatMessage.ts	pinChatMessage	单一（telegram）	在聊天中置顶消息。
scripts/unpinChatMessage.ts	unpinChatMessage	单一（telegram）	取消置顶消息（或最近置顶的消息）。
scripts/getMe.ts	getMe	单一（telegram）	获取机器人的身份信息并验证令牌。
scripts/getChat.ts	getChat	单一（telegram）	根据 ID 或 @username 获取聊天信息。
scripts/listRecentChats.ts	listRecentChats	单一（telegram）	列出机器人最近互动过的聊天（chat_id 解析器）。
scripts/getChatMember.ts	getChatMember	单一（telegram）	获取成员在聊天中的状态和角色。
scripts/getChatAdministrators.ts	getChatAdministrators	单一（telegram）	列出聊天的管理员。
scripts/getChatMemberCount.ts	getChatMemberCount	单一（telegram）	获取聊天中的成员数量。
scripts/getFile.ts	getFile	单一（telegram）	获取文件的元数据和下载路径。

歧义处理与拒绝

• 发送前先解析 chat_id，不要猜测。 chat_id 是数字 ID（超级群组／频道以 -100 开头）或公开的 @username。如果用户提到的聊天没有对应的 ID，请通过 listRecentChats（最近给机器人发送过消息的聊天）或 getChat（已知的 ID／用户名）进行解析。如果 listRecentChats 返回两个聊天，且它们的名称与用户描述的匹配程度相同，请停止并询问用户要选哪一个——分别列出它们的 type 和 ID。如果恰好只有一个匹配项，就对其执行操作；不要过度追问。
• 机器人必须可联系。 机器人只能向自己加入的聊天发送消息，且不能主动发起私聊——用户必须先给机器人发消息。如果发送失败并提示“机器人无法发起对话”或“找不到聊天”，请说明情况并停止；不要改为向其他聊天重试。
• 不支持的操作。 此连接器不会创建／管理聊天、封禁或提升成员权限、管理邀请链接、上传本地文件（请改为提供 HTTPS URL 或 Telegram file_id），也不会运行游戏／处理付款。如果用户要求执行这些操作，请说明不支持；不要改用其他工具，也不要谎称完成了未执行的操作。

身份验证

每种调用形式都通过一个连接选择器传递身份验证信息，而不是密钥——格式为 [<resolver>:]<value>。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层进行路由）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请查看此连接器自己的解析器，不要想当然。<resolver>: 前缀是可选的；不带前缀的值会交给第一个认领它的解析器——UUID 格式的不带前缀值总会被 zapier: 认领。每个脚本都会声明所需的连接以及各连接接受的解析器。传递连接的确切语法（以及如何查看此连接器的解析器列表）因调用形式而异——请参阅上文加载的参考文档。

想先检查已配置的内容？不要为此输出环境变量值——env 或 env | grep <name> 会连同名称一起打印变量值；如果其中设置了有效凭据，就会将其泄露到对话记录中。只检查名称（env | cut -d= -f1 | grep -i <name>），或直接测试已知名称（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式，并按照对应参考文档中的流程获取连接；不要直接询问用户连接 ID 或令牌，仿佛他们早已记得这些信息：

	加载
直接传递凭据	references/use-without-zapier.md
通过 Zapier 连接进行路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 信封：

• data — 脚本的结果（其形状由 outputSchema 声明；有关如何检查脚本的确切形状，请参阅你之前加载的参考文档）。
• meta.outputDataValidation — 对 data 进行验证的结果：
  • { skipped: false, droppedPaths: null } — 已验证，未移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剥离：脚本从 API 返回了这些字段，但 outputSchema 未声明它们。如果需要这些字段，请重新运行并跳过输出验证。
  • { skipped: true } — 已绕过验证；data 是未经检查的脚本原始输出。

读取已剥离字段 / skipOutputDataValidation。 若要接收未经验证的原始结果，请选择退出输出验证（确切语法因形状而异；请参阅你之前加载的参考文档）。输入验证不会跳过。

精简结果 / filterOutputData。 若要将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（确切语法同样因形状而异）。jq 只会处理 data，而非 { data, meta } 信封，因此表达式应以 data 为根（运行脚本的 --help，或对应形状的等效命令，以查看其输出架构）。转换后的值会替换 data，meta 保持不变，并且结果不会根据输出架构重新验证。

参考文档

在相关领域开始工作前，请加载匹配的参考文件：

参考文档	涵盖内容	加载时机
references/telegram-api-gotchas.md	HTML 与 MarkdownV2 转义、文件 URL 大小限制、getFile 的 1 小时链接、复制与转发、删除或置顶消息、构建投票、ok:false/error_code/retry_after/migrate_to_chat_id 错误信封、速率限制	发送格式化文本、上传或下载文件、复制或转发、删除或置顶消息、构建投票，或处理 API 错误和速率限制前。