Translation Comparison - telegram

Back to Details

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scripts for a Telegram bot, against the Telegram Bot API (

https://api.telegram.org/bot<token>/<method>

). Send text, media, locations, contacts, and polls; edit, delete, forward, copy, and pin messages; and resolve the chats, members, and files a bot interacts with. Every script acts as the bot — the bot must be a member of any chat it messages, and a user must message the bot first before the bot can DM them.

Independent, unofficial connector for Telegram. Not affiliated with, endorsed by, or sponsored by Telegram. "Telegram" is a trademark of its owner, used only to identify the service this connector works with.

针对Telegram Bot API（

https://api.telegram.org/bot<token>/<method>

）编写的Telegram机器人脚本。支持发送文本、媒体、位置、联系人与投票；编辑、删除、转发、复制与置顶消息；以及解析机器人交互的对话、成员与文件。所有脚本均以机器人身份运行——机器人必须是其发送消息的对话成员，且用户必须先向机器人发送消息，机器人才可向用户发送私信。

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

When to use this

适用场景

An agent needs a Telegram bot to send a message, photo, document, video, audio, location, contact, or poll to a chat.
An agent needs to manage messages the bot sent — edit, delete, forward, copy, pin, or unpin.
An agent needs to resolve a chat or member — find a
```
chat_id
```
(via
```
listRecentChats
```
), confirm a chat (
```
getChat
```
), check a member's role (
```
getChatMember
```
), or list admins.

Agent需要Telegram机器人向对话发送消息、照片、文档、视频、音频、位置、联系人或投票。
Agent需要管理机器人发送的消息——编辑、删除、转发、复制、置顶或取消置顶。
Agent需要解析对话或成员信息——通过
```
listRecentChats
```
获取
```
chat_id
```
，通过
```
getChat
```
确认对话信息，通过
```
getChatMember
```
检查成员角色，或列出管理员。

Setup

设置

This is an agentskills.io skill.

If the connector has not been installed as a skill yet, install it first with

npx skills add zapier/connectors --skill telegram

(or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or

zapier-sdk

auth commands, run

npm install --omit=dev

here once. Importing the published package as a dependency in your own project instead? That

npm install

already resolves everything — see

references/use-as-sdk.md

Want the actual repo source instead — to browse

references/

, run this connector's tests, or hack on it? See

README.md

for a scoped

git clone

The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:

You have...	Load
An MCP-aware client — tools may already be loaded (e.g. `mcp__telegram__<tool>` ), or you can register a local server yourself (or guide the user to)	`references/use-as-mcp.md`
Terminal / subprocess access (you can run `node` )	`references/use-as-cli.md`
Only your own code, importing this package as a dependency	`references/use-as-sdk.md`
No tool access, no terminal, no ability to import this package — you write your own code that calls the Telegram API directly (e.g. a code-execution sandbox)	`references/use-as-recipe.md`

这是一款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

了解范围化的

git clone

方法。

该连接器运行于**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`

Scripts

脚本

All scripts use a single

telegram

connection.

Script	Script name	Connections	Description
`scripts/sendMessage.ts`	`sendMessage`	Single ( `telegram` )	Send a text message to a chat.
`scripts/sendPhoto.ts`	`sendPhoto`	Single ( `telegram` )	Send a photo by URL or file_id.
`scripts/sendDocument.ts`	`sendDocument`	Single ( `telegram` )	Send a file/document by URL or file_id.
`scripts/sendVideo.ts`	`sendVideo`	Single ( `telegram` )	Send a video by URL or file_id.
`scripts/sendAudio.ts`	`sendAudio`	Single ( `telegram` )	Send an audio file (music) by URL or file_id.
`scripts/sendLocation.ts`	`sendLocation`	Single ( `telegram` )	Send a point on the map.
`scripts/sendContact.ts`	`sendContact`	Single ( `telegram` )	Send a phone contact.
`scripts/sendPoll.ts`	`sendPoll`	Single ( `telegram` )	Send a poll or quiz.
`scripts/editMessageText.ts`	`editMessageText`	Single ( `telegram` )	Edit the text of a message the bot sent.
`scripts/deleteMessage.ts`	`deleteMessage`	Single ( `telegram` )	Delete a message from a chat.
`scripts/forwardMessage.ts`	`forwardMessage`	Single ( `telegram` )	Forward a message, keeping attribution.
`scripts/copyMessage.ts`	`copyMessage`	Single ( `telegram` )	Copy a message's content without attribution.
`scripts/pinChatMessage.ts`	`pinChatMessage`	Single ( `telegram` )	Pin a message in a chat.
`scripts/unpinChatMessage.ts`	`unpinChatMessage`	Single ( `telegram` )	Unpin a message (or the most recent pin).
`scripts/getMe.ts`	`getMe`	Single ( `telegram` )	Get the bot's identity and verify the token.
`scripts/getChat.ts`	`getChat`	Single ( `telegram` )	Get info about a chat by id or @username.
`scripts/listRecentChats.ts`	`listRecentChats`	Single ( `telegram` )	List chats the bot recently interacted with (chat_id resolver).
`scripts/getChatMember.ts`	`getChatMember`	Single ( `telegram` )	Get a member's status and role in a chat.
`scripts/getChatAdministrators.ts`	`getChatAdministrators`	Single ( `telegram` )	List a chat's administrators.
`scripts/getChatMemberCount.ts`	`getChatMemberCount`	Single ( `telegram` )	Get the number of members in a chat.
`scripts/getFile.ts`	`getFile`	Single ( `telegram` )	Get a file's metadata and download path.

所有脚本均使用单个

telegram

连接。

脚本	脚本名称	连接方式	描述
`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` ）	获取文件的元数据与下载路径。

Disambiguation & refusals

歧义处理与拒绝规则

Resolve
chat_id
before sending; don't guess. A
```
chat_id
```
is a numeric id (supergroups/channels are
```
-100
```
-prefixed) or a public
```
@username
```
. If the user names a chat you don't have an id for, resolve it with
```
listRecentChats
```
(chats that recently messaged the bot) or
```
getChat
```
(a known id/username). If
```
listRecentChats
```
returns two chats whose names tie on what the user said, stop and ask which one — list each with its
```
type
```
and id. If exactly one matches, act on it; don't over-ask.
The bot must be reachable. A bot can only message chats it's a member of, and cannot start a private chat — the user must message the bot first. If a send fails with "bot can't initiate conversation" or "chat not found", say so and stop; don't retry against a different chat.
Declined operations. This connector does not create/manage chats, ban or promote members, manage invite links, upload local files (provide an HTTPS URL or a Telegram
```
file_id
```
instead), or run games/payments. If asked for one of these, say it's unsupported — don't substitute another tool and report success for an action you didn't perform.

发送前先解析
chat_id
，切勿猜测。
```
chat_id
```
是数字id（超级群组/频道以
```
-100
```
开头）或公开的
```
@username
```
。如果用户提及的对话你没有对应的id，请通过
```
listRecentChats
```
（最近与机器人互动的对话）或
```
getChat
```
（已知id/username）进行解析。如果
```
listRecentChats
```
返回两个名称与用户描述匹配的对话，请停止操作并询问用户选择哪一个——列出每个对话的
```
type
```
和id。如果恰好有一个匹配项，则直接执行操作；无需过度询问。
机器人必须可触达。机器人只能向其所在的对话发送消息，且无法主动发起私人对话——用户必须先向机器人发送消息。如果发送失败并提示“机器人无法发起对话”或“未找到对话”，请告知用户并停止操作；切勿尝试向其他对话重试。
**不支持的操作。**本连接器不支持创建/管理对话、封禁或提升成员权限、管理邀请链接、上传本地文件（请提供HTTPS URL或Telegram的
```
file_id
```
），或运行游戏/支付功能。如果用户请求此类操作，请告知其不支持；切勿替换为其他工具并谎称操作成功。

Auth

认证

Every shape passes auth as one connection selector, not the secret — a

[<resolver>:]<value>

string. Every connector accepts

zapier:<connection-id>

(Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The

<resolver>:

prefix is optional; a bare value goes to the first resolver that claims it — a UUID-shaped bare value always claims

zapier:

. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.

Checking what's already configured first? Don't dump environment values to do it —

env

env | grep <name>

prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (

env | cut -d= -f1 | grep -i <name>

) or test a known name directly (

[ -n "$VAR_NAME" ]

No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:

	Load
Pass the credential directly	`references/use-without-zapier.md`
Route it through a Zapier connection	`references/use-with-zapier.md`

所有配置均通过单个连接选择器传递认证信息，而非密钥——格式为

[<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`

Output format

输出格式

Every script returns a

{ data, meta }

envelope:

data
— the script's result (the shape its
```
outputSchema
```
declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
meta.outputDataValidation
— what validating
```
data
```
did:
- ```
{ skipped: false, droppedPaths: null }
```
  — validated, nothing removed.
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  — validated, but those paths were stripped from
```
data
```
  : fields the script returned from the API that the
```
outputSchema
```
  doesn't declare. If you need them, re-run with output validation skipped.
- ```
{ skipped: true }
```
  — validation was bypassed;
```
data
```
  is the raw, unchecked script output.

Reading dropped fields /
skipOutputDataValidation
. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.

Trimming the result /
filterOutputData
. To shrink a large result down to the fields you need, pass a jq expression that post-processes

data

(again, exact syntax per shape). The jq runs against

data

only, NOT the

{ data, meta }

envelope, so write it rooted at

data

(run the script's

--help

— or your shape's equivalent — to see its output schema). The transformed value replaces

data

meta

is preserved, and the result is NOT re-validated against the output schema.

每个脚本都会返回

{ data, meta }

格式的结果包：

data
——脚本的执行结果（符合其
```
outputSchema
```
声明的结构；请查看你加载的参考文档，了解如何在你的环境中查看脚本的确切输出结构）。
meta.outputDataValidation
——对
```
data
```
的验证结果：
- ```
{ skipped: false, droppedPaths: null }
```
  ——已验证，未移除任何内容。
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  ——已验证，但这些路径已从
```
data
```
  中移除：脚本从API返回但
```
outputSchema
```
  未声明的字段。如果需要这些字段，请在运行时跳过输出验证。
- ```
{ skipped: true }
```
  ——已跳过验证；
```
data
```
  是原始的未校验脚本输出。

读取被移除的字段 /
skipOutputDataValidation
。要接收原始的未校验结果，请选择跳过输出验证（确切语法因环境而异——请查看你加载的参考文档）。输入验证永远不会被跳过。

精简结果 /
filterOutputData
。要将大结果精简到你需要的字段，请传递一个jq表达式对

data

进行后处理（同样，确切语法因环境而异）。jq仅针对

data

运行，而非

{ data, meta }

结果包，因此请以

data

为根编写表达式（运行脚本的

--help

命令——或你的环境中的等效命令——查看其输出结构）。转换后的值会替换

data

，

meta

会被保留，且结果不会再次根据输出结构进行验证。

References

参考文档

Load the matching reference file before working in that area:

Reference	Covers	Load it when
references/telegram-api-gotchas.md	HTML vs MarkdownV2 escaping, file URL size limits, `getFile` 1-hour links, copying vs forwarding, deleting/pinning messages, building polls, `ok:false` / `error_code` / `retry_after` / `migrate_to_chat_id` error envelope, rate limits	Before sending formatted text, uploading/downloading files, copying vs forwarding, deleting/pinning messages, building polls, or handling API errors and rate limits.

在对应场景下工作前，请加载匹配的参考文档：

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