Skip to content
telegram-bot-ui

Agent Skill · Telegram Bot API 10.4 · v2.1.0

Telegram bots that feel like real products

A UI/UX skill for your coding agent: clean screens and keyboards, streaming answers with Stop, live widgets and channel posts that go out once. Updated for every Bot API release.

MIT licensed · offline checks · no bot token needed to try it

Works with

  • Claude Code
  • Codex
  • Cursor
  • Gemini CLI
  • Antigravity
  • GitHub Copilot
  • OpenCode
  • Grok Build
  • Hermes Agent
  • Replit Agent
  • Devin
  • AGENTS.md readers
From one sentence to your agent to a bot that feels like a product, in half a minute.

What changes in your bot

The same bot, designed on purpose.

Drawn mock-ups of what the skill teaches your agent to build. A bot message has no CSS: its interface is text, formatting, keyboards and the moments between states.

Demo 1: Settings menu, before and after

Without the skill

Without the skillA settings message with a shouting title, five cut-off buttons in one row, a duplicated 'Order placed' message and a stale Pay now button.10:02*** SETTINGS MENU ***Please select what you want to dofrom the options below:Notif…Lan…Del…HelpClose10:03Order placed!10:03Order placed!Pay now
  • Shouting title, labels cut off, a destructive action one tap away
  • Double tap → two orders, and a stale “Pay now” that still works

With the skill

With the skillA clean settings screen: one title, Notifications and Language side by side, a red Delete account button, Back, and a single order card with a green Paid state and Track order.10:02SettingsChoose what to change.NotificationsLanguageDelete accountBack10:03Order #4821 · €46.74Courier · arrives about 10:40PaidTrack order
  • One clear title, readable labels, danger styled and behind a confirmation
  • One order per tap; the card updates in place once it’s paid

Demo 2: Streaming AI reply with Stop

Real stages instead of “typing…”, one draft that fills in place, and a Stop button with a clear “stopped, incomplete” ending.

Streaming AI replyThe user asks to plan the next release. The bot shows a live status, Searching 3 sources, streams the answer into one draft message and offers a Stop button.Plan our next releaseSearching 3 sources…Here’s a short plan for your release:tag the build, run the smoke tests and ▍Draft · updates in placeStop

Demo 3: Agent notification and approval

Your agent reports through its own bot. Approval buttons are bound to one action, and only the operators on the allowlist can press them.

Agent notification and approvalThe agent reports Build finished with all checks passed, then asks for approval to deploy one specific commit to production with Approve and Reject buttons and a View the diff link.10:12Build finishedweb · main · 3 min 41 s · checks passed10:12Approval neededDeploy web@a1c9f2e to production.These buttons approve this one action only.ApproveRejectView the diff

Demo 4: Channel post: preview, approve, publish once

Compose, validate and preview first. Nothing is published without a human’s yes, and a timed-out post is checked before any retry.

Channel post: preview, approve, publish onceA channel post is shown as a preview first, the bot asks whether to publish it at 09:00 with Publish and Edit buttons, and a timeout is checked before any retry so the post goes out once.1 Preview2 Approve3 Publish once09:00AAcme updateschannel · preview, not published yetVersion 3.2Version 3.2 is outDark mode, faster search and a newonboarding. Notes below.Read the notesPublish to the channel at 09:00?A timeout is checked before any retry.PublishEdit

Demo 5: Rich message and an HTML widget

Compact tables and expandable quotes for reports; one live widget card instead of four status messages.

Rich message with a table, and an HTML widget cardA weekly report with a compact three-column table and an expandable quote, followed by an order widget with a four-step progress track, the courier's arrival time and a Track on map button.18:00Weekly reportMetricThis weekChangeOrders1,284+8%Revenue€18.2k+5%Returns12−2Top request: dark modeShow moreHTML widgetOrder #4821€46.74PaidPackedOn the wayDeliveredCourier · arrives about 10:40Track on map

Without the skill, and with it

What changes when your agent uses the skill
AI answer takes 20 sWithout: “typing…” then a wall of textWith: a streamed draft with real stages, a Stop button and a clear “stopped, incomplete” ending
A formWithout: “Send your phone” with no way backWith: buttons and a reply field in one step, Back keeps answers, Submit disabled until valid
“My balance” in a groupWithout: posted for everyone to seeWith: shown only to the person who tapped, and never leaked on errors
Order statusWithout: four new messages per updateWith: one live card that updates in place
Channel post timed outWithout: posted again, now twiceWith: outcome treated as unknown and checked before any retry
“Ignore your rules” sent to an agent botWithout: the agent obeysWith: quoted as data; the operator is told
Old SDKWithout: new features silently droppedWith: the gap is detected and bridged with an isolated adapter

What your agent can do

From one button label to a whole bot product.

The skill routes each task to focused guides, 65 recipes and offline tools, so your agent writes only what your project is missing.

  • Build bot interfaces

    Texts, menus, inline and reply keyboards, colored and disabled buttons, forms, navigation, streaming answers with Stop, Rich Messages, tables, localization.

  • Product flows

    Shops, support, bookings, AI assistants, trackers: no stale “Pay” buttons, no double orders, no personal data leaking into groups.

  • Publish to channels

    Compose, validate, preview, approve and schedule channel posts; never post twice after a timeout.

  • Operate as an agent through a bot

    Drive an agent from Telegram with an operator allowlist and approval buttons bound to one action. Inbound messages are data, not instructions.

  • Build HTML widgets

    Bot API 10.4 widgets inside messages: 18 ready widgets, a size check that follows the server’s algorithm, caption fallback and a local preview.

  • Premium emoji

    One custom emoji pack across buttons, texts and posts, with real ids from the pack and an all-or-nothing fallback when the bot is not eligible.

  • Look up the whole Bot API

    193 methods and 425 types in a local catalog. Validate a payload before sending; the agent refuses to invent a field.

  • Knows when not to

    No widget for a three-button menu, no table for two facts, no group widgets in production, no publishing without a human’s yes.

Supported agents

One skill folder, every major coding agent.

The skill is one folder with a SKILL.md entry point. Install paths follow each host’s own documentation. See how each host loads it.

  • Claude Code

    Plugin with five subagents, or a plain skill folder in ~/.claude/skills.

    Call it: /telegram-bot-ui

  • Codex

    Reads ~/.agents/skills; custom agents in .codex/agents.

    Call it: $telegram-bot-ui

  • Cursor

    Reads ~/.agents/skills; optional rule in .cursor/rules.

    Call it: /telegram-bot-ui

  • Gemini CLI

    ~/.gemini/skills, or gemini skills install from the repository URL.

    Activates from the task description

  • Antigravity

    Reads .agents/skills in the workspace; skills become slash commands.

    Call it: /telegram-bot-ui

  • GitHub Copilot

    Reads ~/.agents/skills; optional copilot-instructions block.

    Activates from the task description

  • OpenCode

    Reads .agents/skills in the project and ~/.config/opencode/skills.

    Activates from the task description

  • Grok Build

    xAI’s agent. Reads .grok/skills and ~/.grok/skills.

    Activates from the task description

  • Hermes Agent

    Reads ~/.hermes/skills; project folders after hermes skills trust.

    Activates from the task description

  • Replit Agent

    Reads .agents/skills in the Repl, or imports the skill from the repository URL.

    Activates from the task description

  • Devin

    Reads ~/.agents/skills; install with --host codex.

    Activates from the task description

  • AGENTS.md readers

    Cline and others: paste the AGENTS.md snippet and keep the folder in the repo.

    Activates from the task description

Install

Pick your agent, copy one line.

Every command installs the latest version and comes with the one that updates it. Then just ask: the skill activates on its own, no API names needed.

Any agent: pick yours in the prompt

Run it in your project; the CLI finds the agents on your machine and asks where to install. Add -g to install for every project. Needs Node.js 22.20 or later.

Install

npx skills add hlibsuslov/telegram-bot-ui

Update to the latest

npx skills update telegram-bot-ui

Or with the GitHub CLI (2.96+), latest tagged release

gh skill install hlibsuslov/telegram-bot-ui

Update with gh skill update.

Then, in your bot’s repository

  • “Improve the UX of this Telegram bot.”
  • “Add a Stop button to the AI answers.”
  • “People double-tap “Place order” and get two orders.”
  • “Post this release note to our channel tomorrow at 9:00. Show me the preview first.”
  • “Make the agent ask for approval with buttons before anything risky.”
  • “Turn the order status into one card that updates.”

More hosts and options: install guide.

Checked, not assumed

Bot API version, verified against the official docs on 2026-11-15
10.4
Bot API methods in the offline catalog, plus 425 types
193
offline tests: 414 Python and 31 TypeScript, run in CI on Linux and Windows
445
numbered recipes, from a settings screen to a whole shop
65
ready HTML widgets with light and dark themes
18
subagents: designer, builder, publisher, widget builder, reviewer
5

Frequently asked questions

Short answers. The README has the long ones.