Skill: shingo0620/telegram-rich-messages (version 1.0.1)

--- name: telegram-rich-messages description: Comprehensive guide for Telegram Rich UI features (Inline buttons, formatting, media, reactions, and message management). Use this skill to provide a low-friction, interactive experience for Telegram users, prioritizing buttons over typing. metadata: { "openclaw": { "requires": { "plugins": ["telegram"] } }, } --- # Telegram Rich Messages This skill transforms the agent from a text-only chatbot into an interactive Telegram assistant. ## Core Principle: Low-Friction Interaction **Typing is slow and error-prone.** Always prioritize Rich UI elements to minimize the user's need to reply with text. If a user has a choice to make, give them a button. ## Quick Navigation Detailed guides for each feature: 1. **[decision-matrix.md](references/decision-matrix.md)**: When to use which UI element. 2. **[formatting.md](references/formatting.md)**: Markdown V2, HTML, and Auto-Copy (Monospace) tricks. 3. **[interactive-ui.md](references/interactive-ui.md)**: How to send stable Inline Buttons and Quick Replies. 4. **[media-and-actions.md](references/media-and-actions.md)**: Sending files, stickers, using reactions, and editing/deleting messages. ## Best Practices - **Monospace for Data**: Use code blocks for IDs, addresses, or snippets. Users can tap to copy them instantly on mobile. - **Stable Buttons**: Always use the `message` tool's `buttons` parameter instead of string directives (`[[buttons:...]]`) for 100% reliability. - **Contextual Actions**: After completing a task, provide buttons for the most likely next steps (e.g., "Check Status", "Delete", "Settings"). - **Direct Uploads**: Telegram supports direct file uploads. No need for Google Drive or external hosting.

path: README.md
content: # OpenClaw Skill: Telegram Rich Messages

A comprehensive guide and template collection for sending interactive and visually structured messages on Telegram using OpenClaw.

## Overview

This skill transforms your OpenClaw agent from a text-only chatbot into a professional Telegram assistant. It leverages Telegram's unique UI features like Inline Buttons, Monospace auto-copy, and direct media transfers while providing fail-safe strategies for maximum reliability.

## Key Features

- **Reliable Buttons**: Prioritizes using the `message` tool for 100% stable button rendering.
- **Smart Formatting**: Guides on using Markdown V2 and HTML, including Spoilers and Links.
- **Low-Friction Copy**: Deep integration with Telegram mobile's "Tap-to-Copy" feature for technical data.
- **CJK-Aware Layouts**: Specialized advice on using Bullet Lists instead of Tables to avoid Chinese/Japanese/Korean alignment issues.
- **Direct Media SOP**: Best practices for sending local files, voice notes, and video messages.

## 🚀 Core Principle: Low-Friction Interaction

**Typing is slow and error-prone.** This skill trains agents to always provide buttons or auto-copyable blocks whenever a choice or a data point is presented to the user.

## Installation

Add this skill to your OpenClaw workspace:

1. Clone this repository into your `~/.openclaw/workspace/skills/` directory.
2. Ensure `channels.telegram.capabilities.inlineButtons` is set to `"all"` or `"dm"` in your `openclaw.json`.
3. Restart the OpenClaw gateway.

## Repository Structure

- `SKILL.md`: Main skill definition and interaction principles.
- `references/decision-matrix.md`: When to use which Telegram UI element.
- `references/interactive-ui.md`: How to send stable buttons and keyboards.
- `references/formatting.md`: Guide on Markdown V2, Spoilers, and CJK alignment.
- `references/media-and-actions.md`: Sending files, stickers, and managing messages.

---
Created with ❤️ by 小蝦 (Xiaoxia) for the OpenClaw community.

---
*Last Sync Test: Sat Feb 21 05:56:32 UTC 2026*


path: references/decision-matrix.md
content: # Telegram UI Decision Matrix

Use this guide to choose the best UI element for your specific scenario.

| Scenario | Recommended UI | Why? |
| :--- | :--- | :--- |
| **Simple binary choice** (Yes/No, Confirm/Cancel) | **Inline Buttons** | Immediate feedback, keeps chat clean. |
| **Multi-choice navigation** (e.g., Settings menu) | **Inline Buttons** | Can lead to different actions/sub-menus without user typing. |
| **Guided input** (e.g., Choose a category) | **Inline Buttons** | Pre-defined options prevent typos and misinterpretation. |
| **Sharing sensitive/technical data** (IDs, Tokens) | **Monospace Block** | Tap-to-copy on mobile is the lowest friction way to extract data. |
| **Confirming a destructive action** (Delete, Clear) | **Inline Buttons** | Provides a physical safety gate before execution. |
| **Long lists of files/results** | **Markdown Table** | Renders as monospaced block; clean and structured. |
| **Frequent repetitive commands** | **Custom Menu Commands** | Available via the `/` menu; no need to remember syntax. |
| **Sending an image/PDF/File** | **Direct Media Send** | Native file support; user can preview/save instantly. |
| **Acknowledging a message** | **Reaction (Emoji)** | Low noise; shows the bot is working/received the info. |

## Friction Levels (Lower is better)
1. **Reaction** (0 friction) - Acknowledgment.
2. **Inline Button** (1 tap) - Decision making.
3. **Monospace Copy** (1 tap + 1 paste) - Data extraction.
4. **Text Reply** (Many taps) - High friction; avoid if possible.


path: references/formatting.md
content: # Telegram Formatting Guide

OpenClaw automatically converts Markdown-style text into Telegram-compatible HTML. **Avoid using raw HTML tags** (like `<u>` or `<b>`) as they may be auto-escaped and displayed as literal text.

## Core Formatting (Recommended)
Use these Markdown-style markers for the most reliable rendering:

- **Bold**: `**text**`
- **Italic**: `_text_`
- **Strikethrough**: `~~text~~`
- **Spoiler (Hide text)**: `||text||` (Click to reveal)
- **Hyperlinks**: `[text](url)`

### ⚠️ Underline Limitation
Standard Markdown underline (`__text__`) is often rendered as **Bold** in this environment. Raw HTML `<u>` tags are usually escaped.
**Recommendation**: Use **Bold** or **Italic** for emphasis instead of Underline to ensure consistent rendering across all Telegram clients.

## Interactive Emojis
Sending certain single emojis will trigger animations on Telegram:
- **Dice**: `🎲` (Rolls a random number 1-6)
- **Slot Machine**: `🎰`
- **Other**: `🎯`, `🏀`, `⚽`, ` bowling`

## The "Auto-Copy" Trick (Monospace)
Telegram mobile clients have a unique feature: **Tapping a monospace block copies it to the clipboard.**

### Inline Code
Use backticks for short snippets:
`Your ID: ` `Ud3ceadc38...`

### Code Blocks
Use triple backticks for multi-line data or when you want a larger "tap area":
```text
Project: Apollo
Status: Active
Latest ID: ABC-123
```

## Lists and Tables
- **Lists (Recommended for CJK)**: Use standard bullet points (`-` or `*`). This is the most reliable way to display mixed-language content without alignment issues.
- **Tables**: Markdown tables are converted to monospaced text blocks. 
  - ⚠️ **CJK Alignment Issue**: In monospaced fonts, Chinese/Japanese/Korean characters and Emojis are usually "double-width" while Latin characters are "single-width". Standard Markdown tables often fail to align these correctly.
  - **Best Practice**: If your content contains Chinese characters or Emojis, **avoid tables** and use **Bullet Lists** instead for a cleaner look.


path: references/interactive-ui.md
content: # Telegram Interactive UI

## Inline Buttons (Recommended)
Inline buttons are attached directly to a message. Clicking them sends a `callback_query` back to the bot.

### How to use (Standard Method)
Always use the `message` tool with the `buttons` parameter for maximum reliability.

```json
{
  "action": "send",
  "channel": "telegram",
  "target": "telegram:2136878064",
  "message": "What would you like to do next?",
  "buttons": [
    [
      { "text": "🎨 Start Creation", "callback_data": "start_apollo" },
      { "text": "📧 Check Mail", "callback_data": "check_mail" }
    ],
    [
      { "text": "⚙️ Settings", "callback_data": "show_settings" },
      { "text": "🌐 Visit Website", "url": "https://example.com" }
    ]
  ]
}
```

### Layout Rules
- `buttons` is an array of arrays (rows of buttons).
- **One button per row**: Best for mobile clarity.
- **Two buttons per row**: Good for binary choices (Yes/No).
- **Max rows**: 10 (keep it concise).

## Quick Replies (Reply Keyboard)
This feature replaces the user's keyboard with large buttons. 

### Usage via Directive
If you must use a string tag, place it at the very end of your response:
`[[quick_replies: Option 1, Option 2, Option 3]]`

*Note*: Directives are less stable than the `message` tool. Prefer Inline Buttons for mission-critical interactions.

## Interactive Flow Strategy
1. **The Question**: Clearly state the choice.
2. **The Buttons**: Provide concise labels (1-2 words + emoji).
3. **The Feedback**: When a button is clicked, acknowledge the action immediately (e.g., "Starting creation...").


path: references/media-and-actions.md
content: # Telegram Media & Message Actions

## Direct File Transfers
Telegram supports sending files directly from the agent's filesystem.

### Sending a File
Use the `message` tool with the `media` parameter pointing to a local path or URL.
```json
{
  "action": "send",
  "channel": "telegram",
  "target": "telegram:2136878064",
  "message": "Here is the PDF report.",
  "media": "/tmp/report.pdf"
}
```

### Voice Notes and Video Notes
- **Voice Note**: Set `asVoice: true` in the `send` action. This sends audio as a native Telegram voice message.
- **Video Note**: Set `asVideoNote: true` in the `send` action. This sends video as a native "Round Video".

## Reactions
Reactions are a low-noise way to acknowledge messages.

### Adding a Reaction
Use the `message` tool with `action: "react"`.
```json
{
  "action": "react",
  "channel": "telegram",
  "target": "telegram:2136878064",
  "messageId": "12345",
  "emoji": "👍"
}
```

## Stickers
If enabled in config, you can send and search for stickers.

- **Send**: `action: "sticker"` with `fileId`.
- **Search**: `action: "sticker-search"` with `query`.

## Message Management
- **Edit**: Use `action: "edit"` to update a message you previously sent. Great for showing progress or changing state (e.g., "Starting..." -> "Done!").
- **Delete**: Use `action: "delete"` to remove sensitive or temporary messages.

## Best Practices for Media
- **Captions**: Always include a descriptive message when sending media.
- **Audio as Voice**: Include `[[audio_as_voice]]` in your response to force an audio file to be sent as a voice note.
- **Video Notes**: Use `asVideoNote: true` in the tool call for round "video messages".


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)