Telegram Openapi Skill

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

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 UXC resolves the curated Telegram Bot API schema through its builtin host mapping. To pin an explicit schema revision instead of the builtin mapping, create the link with: 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