serejaris/telegram-skills / skills/tg-rich-messages
tg-rich-messages
VerifiedUse when sending structured or richly formatted messages from a Telegram bot — tables, section headings, collapsible blocks, photo galleries, maps, math formulas, audio, native styled buttons, bot UI cards, or streaming AI responses. Also use for understanding rich message types and limits when plain sendMessage with parse_mode HTML/Markdown is not sufficient.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.8 KB |
| consumer-integration.md | markdown | 9.9 KB |
| examples.md | markdown | 15.4 KB |
| scripts/rich_ui.py | script | 7.5 KB |
| tests/test_rich_ui.py | script | 6.7 KB |
scripts/rich_ui.py
View on GitHub"""Deterministic Bot API 10.3 UI subset. MIT; no I/O or credentials.
Supported blocks: heading, paragraph, pre, table, details, photo. RichText is
restricted to literal strings. This is intentionally not the full Bot API.
"""
from copy import deepcopy
import re
from urllib.parse import urlsplit
__version__ = '1.4.0'
MAX_TEXT = 32768
MAX_BLOCKS = 500
MAX_DEPTH = 16
MAX_MEDIA = 50
STYLES = frozenset(('danger', 'success', 'primary'))
def _text(value):
if not isinstance(value, str):
raise ValueError('text must be a literal string')
try:
value.encode('utf-8')
except UnicodeError:
raise ValueError('text must be valid Unicode') from None
return len(value)
def _fields(value, required, optional=()):
if not isinstance(value, dict) or not required <= value.keys() or value.keys() - required - set(optional):
raise ValueError('unsupported or missing fields')
def _true_fields(value, names):
for name in names:
if name in value and value[name] is not True:
raise ValueError('optional flag must be true or omitted')
def _photo_reference(value):
if not _text(value) or any(c.isspace() or ord(c) < 32 for c in value):
raise ValueError('invalid photo reference')
if re.fullmatch(r'(?:attach://)?[A-Za-z0-9_-]+', value):
return
try:
parsed = urlsplit(value)
valid = parsed.scheme in ('http', 'https') and bool(parsed.hostname)
except ValueError:
valid = False
if not valid:
raise ValueError('photo requires a file_id, HTTP URL or attach://name')
def build_blocks_message(blocks, *, skip_entity_detection=True):
"""Return a detached InputRichMessage or raise ValueError.
Preflight counts literal Unicode code points; official limits say UTF-8
characters, not bytes. Table rows count toward the 500-block limit.
This does not replace server/client validation of the complete protocol.
"""
if type(skip_entity_detection) is not bool:
raise ValueError('skip_entity_detection must be boolean')
count = chars = media = 0
def visit(items, depth):
nonlocal count, chars, media
if not isinstance(items, list) or not items or depth > MAX_DEPTH:
raise ValueError('blocks must be nonempty and within nesting limit')
for block in items:
if not isinstance(block, dict):
raise ValueError('block must be an object')
kind = block.get('type')
if not isinstance(kind, str):
raise ValueError('block type must be a string')
count += 1
if kind in ('paragraph', 'heading', 'pre'):
required = {'type', 'text'} | ({'size'} if kind == 'heading' else set())
_fields(block, required, ('language',) if kind == 'pre' else ())
chars += _text(block['text'])
if kind == 'heading' and (type(block['size']) is not int or not 1 <= block['size'] <= 6):
raise ValueError('heading size must be 1..6')
if 'language' in block:
_text(block['language'])
elif kind == 'photo':
_fields(block, {'type', 'photo'}, ('caption',))
_fields(block['photo'], {'type', 'media'})
if block['photo']['type'] != 'photo':
raise ValueError('photo block requires photo media')
_photo_reference(block['photo']['media'])
if 'caption' in block:
_fields(block['caption'], {'text'})
chars += _text(block['caption']['text'])
media += 1
elif kind == 'details':
_fields(block, {'type', 'summary', 'blocks'}, ('is_open',))
chars += _text(block['summary'])
_true_fields(block, ('is_open',))
visit(block['blocks'], depth + 1)
elif kind == 'table':
_fields(block, {'type', 'cells'}, ('caption', 'is_compact', 'is_bordered', 'is_striped'))
_true_fields(block, ('is_compact', 'is_bordered', 'is_striped'))
if 'caption' in block:
chars += _text(block['caption'])
rows = block['cells']
if not isinstance(rows, list) or not rows:
raise ValueError('table must contain rows')
for row in rows:
count += 1
if not isinstance(row, list) or not row or len(row) > 20:
raise ValueError('table row must have 1..20 cells')
width = 0
for cell in row:
_fields(cell, {'align', 'valign'}, ('text', 'is_header', 'colspan', 'rowspan'))
if cell['align'] not in ('left', 'center', 'right') or cell['valign'] not in ('top', 'middle', 'bottom'):
raise ValueError('invalid table alignment')
_true_fields(cell, ('is_header',))
if 'text' in cell:
chars += _text(cell['text'])
for span in ('colspan', 'rowspan'):
if span in cell and (type(cell[span]) is not int or cell[span] < 1):
raise ValueError('span must be a positive integer')
width += cell.get('colspan', 1)
if width > 20:
raise ValueError('table row spans exceed 20 columns')
else:
raise ValueError('unsupported block type')
if count > MAX_BLOCKS or chars > MAX_TEXT or media > MAX_MEDIA:
raise ValueError('rich message exceeds documented limits')
try:
visit(blocks, 1)
except RecursionError:
raise ValueError('cyclic or excessive nesting') from None
return {'blocks': deepcopy(blocks), 'skip_entity_detection': skip_entity_detection}
def styled_button(text, *, callback_data=None, url=None, copy_text=None, style=None):
"""Return a native InlineKeyboardButton with exactly one supported action.
RichMessageButton's special 'link' style is not an inline keyboard style.
copy_text is a literal string and becomes CopyTextButton {'text': ...}.
"""
if not _text(text):
raise ValueError('button text must not be empty')
if style is not None and (not isinstance(style, str) or style not in STYLES):
raise ValueError('unsupported inline button style')
actions = [(key, value) for key, value in (('callback_data', callback_data), ('url', url), ('copy_text', copy_text)) if value is not None]
if len(actions) != 1:
raise ValueError('button requires exactly one action')
key, value = actions[0]
length = _text(value)
if key == 'callback_data' and not 1 <= len(value.encode('utf-8')) <= 64:
raise ValueError('callback_data must be 1..64 UTF-8 bytes')
if key == 'copy_text' and not 1 <= length <= 256:
raise ValueError('copy_text must be 1..256 characters')
if key == 'url':
if any(c.isspace() or ord(c) < 32 for c in value):
raise ValueError('invalid button URL')
try:
parsed = urlsplit(value)
except ValueError:
raise ValueError('invalid button URL') from None
if parsed.scheme not in ('http', 'https', 'tg') or not parsed.netloc:
raise ValueError('button URL must use HTTP, HTTPS or tg')
result = {'text': text, key: {'text': value} if key == 'copy_text' else value}
if style is not None:
result['style'] = style
return result
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |