Telegram OpenAPI Skill

---

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/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

1. 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

2. 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

3. 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

4. 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:/getMe

get:/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 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

Operation Groups

Read / Lookup

get:/getMe

get:/getChat

get:/getChatMember

get:/getWebhookInfo

Messaging

post:/sendMessage

post:/sendPhoto

post:/sendDocument

post:/sendMediaGroup

Update Delivery

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/....

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 ... is equivalent to uxc https://api.telegram.org --schema-url ....

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

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.