telegram-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telegram Bot API Skill

Telegram Bot API 技能

Use this skill to run Telegram Bot API operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用本技能可通过

uxc

+ OpenAPI执行Telegram Bot API操作。

复用

uxc

技能以实现共享执行、认证和错误处理指引。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://api.telegram.org
```
.

Access to the curated OpenAPI schema URL:

https://raw.githubusercontent.com/holon-run/uxc/main/skills/telegram-openapi-skill/references/telegram-bot.openapi.json

A Telegram bot token from BotFather.

```
uxc
```
已安装且可在
```
PATH
```
中访问。
可访问
```
https://api.telegram.org
```
的网络权限。

可访问精选OpenAPI Schema的URL：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/telegram-openapi-skill/references/telegram-bot.openapi.json

从BotFather获取的Telegram机器人令牌。

Scope

适用范围

This skill covers a lean bot core surface:

bot identity and chat lookup
text sends
media sends by
```
file_id
```
, HTTP URL, or local multipart upload
polling via
```
getUpdates
```
webhook setup/status/delete operations

This skill does not cover:

multipart media groups with
```
attach://
```
file arrays
generic webhook ingestion/runtime hosting
the full Telegram Bot API surface

本技能覆盖精简的机器人核心功能：

机器人身份与聊天查询
文本消息发送
通过
```
file_id
```
、HTTP URL或本地多部分上传发送媒体
通过
```
getUpdates
```
进行轮询
Webhook的设置/状态查询/删除操作

本技能不包含以下内容：

使用
```
attach://
```
文件数组的多部分媒体组
通用Webhook接收/运行时托管
完整的Telegram Bot API功能

Authentication

认证

Telegram Bot API requires the bot token in the request path:

https://api.telegram.org/bot<TOKEN>/METHOD_NAME

Configure the credential with a request path prefix template:

bash

uxc auth credential set telegram-bot \
  --auth-type api_key \
  --secret-env TELEGRAM_BOT_TOKEN \
  --path-prefix-template "/bot{{secret}}"

uxc auth binding add \
  --id telegram-bot \
  --host api.telegram.org \
  --scheme https \
  --credential telegram-bot \
  --priority 100

Validate the local mapping when auth looks wrong:

bash

uxc auth binding match https://api.telegram.org/getMe

Telegram Bot API要求在请求路径中包含机器人令牌：

https://api.telegram.org/bot<TOKEN>/METHOD_NAME

。

使用请求路径前缀模板配置凭据：

bash

uxc auth credential set telegram-bot \
  --auth-type api_key \
  --secret-env TELEGRAM_BOT_TOKEN \
  --path-prefix-template "/bot{{secret}}"

uxc auth binding add \
  --id telegram-bot \
  --host api.telegram.org \
  --scheme https \
  --credential telegram-bot \
  --priority 100

当认证出现问题时，验证本地映射：

bash

uxc auth binding match https://api.telegram.org/getMe

Core Workflow

核心工作流程

Use the fixed link command by default:

```
command -v telegram-openapi-cli
```

If missing, create it:

uxc link telegram-openapi-cli https://api.telegram.org --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/telegram-openapi-skill/references/telegram-bot.openapi.json

```
telegram-openapi-cli -h
```

Inspect operation schema first:

```
telegram-openapi-cli get:/getMe -h
```

telegram-openapi-cli post:/sendMessage -h

```
telegram-openapi-cli post:/sendPhoto -h
```

telegram-openapi-cli post:/sendDocument -h

telegram-openapi-cli post:/getUpdates -h

Prefer read/setup validation before writes:

```
telegram-openapi-cli get:/getMe
```

telegram-openapi-cli get:/getWebhookInfo

telegram-openapi-cli get:/getChat chat_id=@channel_or_chat_id

Execute operations with key/value or positional JSON:

key/value:

telegram-openapi-cli post:/sendMessage chat_id=CHAT_ID text="Hello from uxc"

multipart upload:

telegram-openapi-cli post:/sendPhoto chat_id=CHAT_ID photo=/tmp/photo.jpg caption="Uploaded by uxc"

positional JSON:

telegram-openapi-cli post:/sendMessage '{"chat_id":"CHAT_ID","text":"Hello from uxc"}'

daemon-backed polling subscribe:

uxc subscribe start https://api.telegram.org post:/getUpdates '{"timeout":5,"allowed_updates":["message","callback_query"]}' --mode poll --poll-config '{"interval_secs":2,"extract_items_pointer":"/result","request_cursor_arg":"offset","cursor_from_item_pointer":"/update_id","cursor_transform":"increment","checkpoint_strategy":{"type":"item_key","item_key_pointer":"/update_id"}}' --sink file:/tmp/telegram-updates.ndjson

默认使用固定链接命令：

```
command -v telegram-openapi-cli
```

若命令不存在，创建链接：

uxc link telegram-openapi-cli https://api.telegram.org --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/telegram-openapi-skill/references/telegram-bot.openapi.json

```
telegram-openapi-cli -h
```

先查看操作Schema：

```
telegram-openapi-cli get:/getMe -h
```

telegram-openapi-cli post:/sendMessage -h

```
telegram-openapi-cli post:/sendPhoto -h
```

telegram-openapi-cli post:/sendDocument -h

telegram-openapi-cli post:/getUpdates -h

在执行写入操作前优先进行读取/设置验证：

```
telegram-openapi-cli get:/getMe
```

telegram-openapi-cli get:/getWebhookInfo

telegram-openapi-cli get:/getChat chat_id=@channel_or_chat_id

使用键值对或位置JSON执行操作：

键值对方式：

telegram-openapi-cli post:/sendMessage chat_id=CHAT_ID text="Hello from uxc"

多部分上传方式：

telegram-openapi-cli post:/sendPhoto chat_id=CHAT_ID photo=/tmp/photo.jpg caption="Uploaded by uxc"

位置JSON方式：

telegram-openapi-cli post:/sendMessage '{"chat_id":"CHAT_ID","text":"Hello from uxc"}'

守护进程支持的轮询订阅：

uxc subscribe start https://api.telegram.org post:/getUpdates '{"timeout":5,"allowed_updates":["message","callback_query"]}' --mode poll --poll-config '{"interval_secs":2,"extract_items_pointer":"/result","request_cursor_arg":"offset","cursor_from_item_pointer":"/update_id","cursor_transform":"increment","checkpoint_strategy":{"type":"item_key","item_key_pointer":"/update_id"}}' --sink file:/tmp/telegram-updates.ndjson

Runtime Validation

运行时验证

The following Telegram polling flow has been validated against the real Bot API through

uxc

```
get:/getMe
```
```
get:/getWebhookInfo
```

daemon-backed

uxc subscribe --mode poll

post:/getUpdates

item-derived offset progression from
```
update_id + 1
```
dedupe/checkpoint behavior for repeated polls

Observed runtime behavior:

```
data
```
events are emitted for real Telegram updates
```
poll
```
events record fetched/emitted/skipped counts
```
checkpoint
```
events are emitted after new updates are seen
repeated polls skip already-consumed updates after checkpoint advancement

以下Telegram轮询流程已通过

uxc

在真实Bot API上验证：

```
get:/getMe
```
```
get:/getWebhookInfo
```

基于守护进程的

uxc subscribe --mode poll

调用

post:/getUpdates

从
```
update_id + 1
```
派生的偏移量递进
重复轮询的去重/检查点行为

观察到的运行时行为：

针对真实Telegram更新触发
```
data
```
事件
```
poll
```
事件记录获取/触发/跳过的数量
发现新更新后触发
```
checkpoint
```
事件
检查点推进后，重复轮询会跳过已消费的更新

Operation Groups

操作分组

Read / Lookup

读取/查询

```
get:/getMe
```
```
get:/getChat
```
```
get:/getChatMember
```
```
get:/getWebhookInfo
```

```
get:/getMe
```
```
get:/getChat
```
```
get:/getChatMember
```
```
get:/getWebhookInfo
```

Messaging

消息发送

```
post:/sendMessage
```
```
post:/sendPhoto
```
```
post:/sendDocument
```
```
post:/sendMediaGroup
```

```
post:/sendMessage
```
```
post:/sendPhoto
```
```
post:/sendDocument
```
```
post:/sendMediaGroup
```

Update Delivery

更新交付

```
post:/getUpdates
```
```
post:/setWebhook
```
```
post:/deleteWebhook
```

```
post:/getUpdates
```
```
post:/setWebhook
```
```
post:/deleteWebhook
```

Guardrails

防护措施

Keep automation on the JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
```
getUpdates
```
and webhook delivery are mutually exclusive:
- if a webhook is configured, call
```
post:/deleteWebhook
```
  before polling with
```
post:/getUpdates
```
- if polling is active, do not treat webhook operations as background subscription support
Telegram allows only one active
```
getUpdates
```
consumer per bot token:
- if another bot process or script is polling at the same time, Telegram returns HTTP 409
- stop the other consumer before relying on daemon-backed polling subscribe

For daemon-backed polling subscribe, prefer item-derived offset progression:

```
extract_items_pointer
```
should be
```
/result
```
```
request_cursor_arg
```
should be
```
offset
```
```
cursor_from_item_pointer
```
should be
```
/update_id
```
```
cursor_transform
```
should be
```
increment
```

checkpoint_strategy.type

should usually be

item_key

with

item_key_pointer=/update_id

```
uxc auth binding match
```
should be checked against a concrete Telegram method URL such as
```
https://api.telegram.org/getMe
```
, because auth is applied through a path-prefix template that expands to
```
/bot<TOKEN>/...
```
.
```
sendPhoto
```
,
```
sendDocument
```
, and
```
sendMediaGroup
```
in this skill accept existing
```
file_id
```
values or HTTP URLs only; they do not upload new local files.
```
sendPhoto
```
and
```
sendDocument
```
also support
```
multipart/form-data
```
local file uploads. File fields must be local path strings.
```
sendMediaGroup
```
still stays JSON-only in this skill because current multipart v1 does not model the
```
media
```
array plus
```
attach://
```
file set cleanly.
```
setWebhook
```
supports multipart certificate upload for self-signed certs through the
```
certificate
```
file field.
Treat
```
post:/sendMessage
```
, all
```
send*
```
operations, and webhook-changing operations as write/high-risk actions; require explicit user confirmation before execution.

telegram-openapi-cli <operation> ...

is equivalent to

uxc https://api.telegram.org --schema-url <telegram_openapi_schema> <operation> ...

仅在JSON输出包上进行自动化操作，请勿使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
```
getUpdates
```
与Webhook交付互斥：
- 若已配置Webhook，在使用
```
post:/getUpdates
```
  进行轮询前需调用
```
post:/deleteWebhook
```
- 若轮询处于活跃状态，请勿将Webhook操作视为后台订阅支持
Telegram每个机器人令牌仅允许一个活跃的
```
getUpdates
```
消费者：
- 若其他机器人进程或脚本同时进行轮询，Telegram会返回HTTP 409
- 在依赖守护进程支持的轮询订阅前，请停止其他消费者

对于守护进程支持的轮询订阅，优先使用基于项的偏移量递进：

```
extract_items_pointer
```
应设为
```
/result
```
```
request_cursor_arg
```
应设为
```
offset
```
```
cursor_from_item_pointer
```
应设为
```
/update_id
```
```
cursor_transform
```
应设为
```
increment
```

checkpoint_strategy.type

通常应设为

item_key

，且

item_key_pointer=/update_id

应针对具体的Telegram方法URL（如
```
https://api.telegram.org/getMe
```
）检查
```
uxc auth binding match
```
，因为认证是通过路径前缀模板扩展为
```
/bot<TOKEN>/...
```
来应用的。
本技能中的
```
sendPhoto
```
、
```
sendDocument
```
和
```
sendMediaGroup
```
仅接受已有的
```
file_id
```
值或HTTP URL；不支持上传新的本地文件。
```
sendPhoto
```
和
```
sendDocument
```
也支持
```
multipart/form-data
```
本地文件上传。文件字段必须为本地路径字符串。
本技能中的
```
sendMediaGroup
```
仍仅支持JSON格式，因为当前的多部分v1版本无法清晰地建模
```
media
```
数组加上
```
attach://
```
文件集合。
```
setWebhook
```
支持通过
```
certificate
```
文件字段上传自签名证书的多部分上传。
将
```
post:/sendMessage
```
、所有
```
send*
```
操作以及更改Webhook的操作视为写入/高风险操作；执行前需获取用户明确确认。

telegram-openapi-cli <operation> ...

等价于

uxc https://api.telegram.org --schema-url <telegram_openapi_schema> <operation> ...

。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
Curated OpenAPI schema:
```
references/telegram-bot.openapi.json
```
Telegram Bot API docs: https://core.telegram.org/bots/api
Local Bot API server: https://github.com/tdlib/telegram-bot-api

使用模式：
```
references/usage-patterns.md
```
精选OpenAPI Schema：
```
references/telegram-bot.openapi.json
```
Telegram Bot API文档：https://core.telegram.org/bots/api
本地Bot API服务器：https://github.com/tdlib/telegram-bot-api