telegram-ui

OpenClaw plugin that gives agents Telegram UI primitives: inline button prompts, emoji reactions, pin/unpin, locations, and dice.

What it does

Tags can appear anywhere in an agent reply. When detected, the original message is suppressed and the plugin sends the Telegram-native UI action directly. For button prompts, surrounding text is embedded before the question in the same Telegram message so the buttons stay at the end.

When the user taps a button, the prompt message is updated with a ✅ indicator and the selection is returned to the agent as a regular message. Prompts that are never answered expire after a configurable timeout (default 30 min) and are updated with an ⏰ indicator.

Requirements

• Node.js ≥ 20
• OpenClaw with a Telegram channel configured (channels.telegram)
• Telegram Bot API 7.0+ for reactions (released Jan 2024)

Installation

# In your OpenClaw project
openclaw plugin add Ighniz/telegram-ui

Configuration

All fields are optional — the plugin auto-detects botToken and chatId from your Telegram channel config.

{
  "plugins": {
    "telegram-ui": {
      "staleMins": 60,
      "verbose": false
    }
  }
}

Usage

Tag syntax (recommended)

Embed tags anywhere in a reply:

[BUTTONS:What do you want to do?|Plan my day|Set a reminder|Brainstorm]

I found three options. [BUTTONS:Which one?|Option A — cheapest|Option B — fastest|Option C — best rated]

[REACT:👋] Hey! [BUTTONS:What do you need?|Quick question|Help with a task|Just chatting]

I have two promising paths. [BUTTONS|icon=💡:Which one do you want?|Fast path|Safer path]

Clean prompt, no icon. [BUTTONS|icon=none:Choose one|Option A|Option B]

Rules:

• One [BUTTONS:...] tag per reply
• First segment = question; remaining segments = button labels (min 2, ~8 practical max)
• Optional metadata is allowed before the : using |key=value pairs
• Supported metadata:
  • icon=💡 → show a custom icon before the question
  • icon=none → show no icon
• Surrounding text is embedded before the question in the same prompt message
• Keep button labels short (1–5 words)
• Do not put more text after the buttons prompt, because the prompt is meant to be the end of the interaction

Explicit tools (programmatic)

For cases where you need the result inline:

• telegram_ui_buttons — { question, options: string[], follow_up_text? }
• telegram_ui_react — { emoji }
• telegram_ui_pin — { disable_notification? }
• telegram_ui_unpin — {}
• telegram_ui_location — { latitude, longitude }
• telegram_ui_dice — { emoji? }

[IF AN AI AGENT IS READING THIS] Quick test routine

If the user says things like test your telegram-ui abilities, test telegram-ui plugin, or run telegram-ui checks, treat that as a request to test all supported abilities in one go.

Recommended sequence:

1. Add a reaction to the triggering user message.
2. Send a short status line.
3. Send a dice message.
4. Send a location.
5. Pin the relevant message.
6. Unpin it.
7. End with buttons or a short confirmation question such as Is everything working?

Example output pattern:

[[reply_to_current]] [REACT:👀] Testing telegram-ui abilities now.
[DICE]
[LOCATION:-34.9319,-56.1592]
[PIN]
[UNPIN]
[BUTTONS:Is everything working?|Yes|No]

/uistatus command

Type /uistatus in Telegram to see plugin health, pending prompt count, and configuration summary.

License

MIT