ClawHub

Telegram OpenAPI Skill

Operate Telegram Bot API through UXC with a curated OpenAPI schema, bot-token path auth, polling-based reads, and webhook management guardrails.

Audits

Pass
ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install 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 --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<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