Telegram Compose

Format and deliver rich, scannable Telegram messages via direct API with HTML formatting.

How This Skill Gets Used

This skill is auto-invoked by the main session agent. No other skills need to know about it.

Decision Rule (for the main session agent)

Before sending a message to Telegram, check:

• - Short reply (<3 lines, no structure): Send directly via OpenClaw message tool. Done.
• Substantive content (>3 lines, or has lists/stats/sections/reports): Spawn this skill as a sub-agent.

Spawning the sub-agent

The main session agent calls sessions_spawn with:

CODEBLOCK0

Task template:

CODEBLOCK1

IMPORTANT: The caller MUST specify which bot account to use. The sub-agent must NOT auto-select or iterate accounts.

CRITICAL: The sub-agent announcement routes back to the main session, NOT to Telegram. So the main session should reply NO_REPLY after spawning to avoid double-messaging. The sub-agent's curl call is what delivers to Telegram.

What the sub-agent receives

1. 1. Skill path — so it can read the formatting rules
2. Bot account name — which Telegram bot account to use (must be specified, never auto-selected)
3. Chat ID — where to send
4. Thread ID — topic thread if applicable
5. Raw content — the unformatted text/data to turn into a rich message

Credentials

Bot token: Stored in the OpenClaw config file under channels.telegram.accounts.<name>.botToken.

The account name is always provided by the caller. Never auto-select or iterate accounts.

CODEBLOCK2

Sending

CODEBLOCK3

Formatting Rules

HTML Tags

CODEBLOCK4

Escaping

Escape these characters in text content only (not in your HTML tags):

• - & → & (do this FIRST to avoid double-escaping)
• INLINECODE6 → INLINECODE7
• INLINECODE8 → INLINECODE9

Common gotcha: content containing & (e.g., "R&D", "Q&A") will break HTML parsing if not escaped.

Structure Pattern

CODEBLOCK5

Style Rules

1. 1. Faux headings: EMOJI <b>CAPS TITLE</b> with blank line after
2. Emojis: 1-3 per message as visual anchors, not decoration
3. Whitespace: Blank lines between sections
4. Long content: Use INLINECODE12
5. Links: Own line, with arrow: INLINECODE13

Examples

Status update:
CODEBLOCK6

Alert:
CODEBLOCK7

List:

✅ <b>PRIORITIES</b>

• <s>Review PR #234</s> — done
• <b>Finish docs</b> — in progress
• Deploy staging

<i>2 of 3 complete</i>

Mobile-Friendly Data Display

Never use <pre> for stats, summaries, or visual layouts. <pre> uses monospace font and wraps badly on mobile, breaking alignment and tree characters. Reserve <pre> for actual code/commands only.

For structured data, use emoji + bold + separators:

CODEBLOCK9

Other patterns:

Record cards:
CODEBLOCK10

Bullet lists:

• <b>hzl-cli:</b> 1.12.0
• <b>skill:</b> 1.0.6

Limits and Splitting

• - Message max: 4,096 characters
• Caption max: 1,024 characters

If formatted message exceeds 4,096 chars:

1. 1. Split at section boundaries (blank lines between <b>HEADING</b> blocks)
2. Each chunk must be valid HTML (don't split inside a tag)
3. Send chunks sequentially with a 1-second delay between them
4. First chunk gets the full heading; subsequent chunks get a continuation indicator: INLINECODE18

Error Handling

If Telegram API returns an error:

Fallback rule: If HTML formatting fails twice, send as plain text rather than not sending at all. Delivery matters more than formatting.

Sub-Agent Execution Checklist

When running as a sub-agent, follow this sequence:

1. 1. Parse the task — extract Bot account name, Chat ID, Thread ID (if any), skill path, and raw content
2. Read this SKILL.md — load the formatting rules
3. Format the content — apply HTML tags, structure pattern, style rules, mobile-friendly data display
4. Escape special chars — & then < then > in text content only (not in your HTML tags)
5. Check length — if >4,096 chars, split at section boundaries
6. Get bot token — auto-detect config path, extract token for the specified account (error if not found)
7. Send via curl — use the appropriate template (with/without thread ID)
8. Check response — parse curl output for INLINECODE27
9. Handle errors — follow the error handling table above
10. Report back — reply with message_id on success, or error details on failure