| name | telegram-openapi-skill |
| description | Operate Telegram Bot API through UXC with a curated OpenAPI schema, bot-token path auth, polling-based reads, and webhook management guardrails. |
Telegram Bot API Skill
Use this skill to run Telegram Bot API operations through uxc + OpenAPI.
Reuse the uxc skill for shared execution, auth, and error-handling guidance.
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.
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
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:
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:
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 -htelegram-openapi-cli post:/sendMessage -htelegram-openapi-cli post:/sendPhoto -htelegram-openapi-cli post:/sendDocument -htelegram-openapi-cli post:/getUpdates -h
-
Prefer read/setup validation before writes:
telegram-openapi-cli get:/getMetelegram-openapi-cli get:/getWebhookInfotelegram-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
Runtime Validation
The following Telegram polling flow has been validated against the real Bot API through uxc:
get:/getMeget:/getWebhookInfo- daemon-backed
uxc subscribe --mode poll on 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 updatespoll events record fetched/emitted/skipped countscheckpoint events are emitted after new updates are seen- repeated polls skip already-consumed updates after checkpoint advancement
Operation Groups
Read / Lookup
get:/getMeget:/getChatget:/getChatMemberget:/getWebhookInfo
Messaging
post:/sendMessagepost:/sendPhotopost:/sendDocumentpost:/sendMediaGroup
Update Delivery
post:/getUpdatespost:/setWebhookpost:/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 /resultrequest_cursor_arg should be offsetcursor_from_item_pointer should be /update_idcursor_transform should be incrementcheckpoint_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> ....
References
