Telegram Interactive Buttons

Requirements

📖 First time setup? See SETUP.md for detailed configuration instructions.

Required Binaries

• - openclaw - OpenClaw CLI (install: npm install -g openclaw)
• INLINECODE2 - Shell for helper scripts

Optional Binaries

• - python3 - For JSON validation script (recommended)

Credentials & Configuration

Telegram Bot Setup Required:

1. 1. Create a Telegram bot via @BotFather

1. 2. Configure OpenClaw with your bot token:

Edit ~/.openclaw/config.json (or your workspace openclaw.json):
CODEBLOCK0

1. 3. Get your chat ID:

Target Format: All examples use telegram:CHAT_ID format. Replace CHAT_ID with your actual Telegram chat ID (numeric).

Security Notes

Scripts in this skill:

• - Execute local shell commands via INLINECODE10
• Call openclaw CLI with user-provided arguments
• INLINECODE12 parses JSON (no external connections)

Before running:

1. 1. Review all scripts - they are short and readable
2. Replace placeholder chat IDs in examples
3. Run only in trusted environments
4. Never pass untrusted inputs to scripts without validation
5. Store bot token securely (use environment variables or secure config files)

Credential Scope:

• - Bot token allows sending messages to chats where bot is added
• Scripts do not modify bot permissions or settings
• No sensitive data is transmitted beyond standard Telegram API calls

Overview

This skill provides reliable methods for creating interactive Telegram messages with inline buttons using the OpenClaw CLI. After extensive testing across different models (Gemini, Claude), the CLI approach via exec tool has proven to be the most stable method for sending buttons.

Why this skill exists: The message tool's buttons parameter can be fragile across different models. The CLI provides consistent, predictable button rendering.

Quick Start

Basic button message:

CODEBLOCK1

Key points:

• - Use single quotes around the entire --buttons argument
• Buttons is a JSON array of arrays (rows)
• Each button needs text and INLINECODE18
• Keep 1-2 buttons per row for mobile UX

Sending Buttons

Button Structure

The --buttons parameter accepts a JSON array of arrays (rows):

CODEBLOCK2

Layout Limits:

• - Max buttons per row: 8 (use this for grids/keypads)
• Max buttons total: 100
• Mobile UX Recommendation: While 8 are supported, keep 1-3 buttons per row for standard menus to ensure readability on mobile. Use the full 8-button width only for grids (e.g., calculators, calendars, or numeric selectors).

Button Properties

Each button object supports:

• - text (required): Display text
• INLINECODE21 (required): Unique identifier for the callback
• INLINECODE22 (optional): primary, success, or INLINECODE25

Example with styles:

CODEBLOCK3

Helper Script

Use the provided helper for cleaner code:

CODEBLOCK4

Handling Callbacks

When a user clicks a button, Telegram sends a callback with the callback_data value. Handle it in two steps:

1. 1. Send confirmation message - Acknowledge the selection
2. Edit original message - Remove buttons to prevent accidental re-clicks

Example flow:

CODEBLOCK5

Editing Messages

Remove buttons after selection:

CODEBLOCK6

Or use the helper:

CODEBLOCK7

Common Patterns

Yes/No Confirmation

CODEBLOCK8

Workflow Menu

CODEBLOCK9

Number Selection

CODEBLOCK10

Best Practices

1. 1. Keep it mobile-friendly - 1-2 buttons per row maximum
2. Use descriptive callback_data - wf_search not INLINECODE28
3. Always edit after callback - Remove buttons to prevent confusion
4. Add visual indicators - Emojis help distinguish button types (✅ 🎬 📊 ⚙️)
5. Validate JSON - Use scripts/validate_buttons.py before sending

Troubleshooting

Common Errors

"buttons[0][0] requires text and callback_data"

• - Cause: Escaped quotes in JSON (\"text\" instead of "text")
• Fix: Use clean JSON without escaping

Buttons not appearing

• - Cause: Invalid JSON structure
• Fix: Validate with INLINECODE32

Multiple buttons per user click

• - Cause: Not editing original message after callback
• Fix: Always edit and remove buttons after handling callback

Resources

scripts/

• - send_buttons.sh - Helper for sending button messages
• INLINECODE34 - Helper for editing messages
• INLINECODE35 - JSON validation before sending

references/

• - REFERENCE.md - Complete parameter reference and advanced examples

assets/examples/

• - basic_yes_no.sh - Simple confirmation dialog
• INLINECODE38 - Multi-option workflow menu
• INLINECODE39 - Complete callback handling flow