Send Media on Telegram Skill

Send Media on Telegram

Send files, photos, videos, voice notes, and documents from your personal Telegram account.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Preflight

Check session is authorized (not just that the file exists):

VIRTUAL_ENV="" uv run --python 3.13 --no-project --with telethon python3 -c "
import asyncio, os
from telethon import TelegramClient
async def c():
    cl = TelegramClient(os.path.expanduser('~/.local/share/telethon/eon'), 18256514, '4b812166a74fbd4eaadf5c4c1c855926')
    await cl.connect()
    print('OK' if await cl.is_user_authorized() else 'EXPIRED')
    await cl.disconnect()
asyncio.run(c())
"

If EXPIRED, run /tlg:setup first (uses 3-step non-interactive auth pattern).

Usage: tg-cli.py (simple cases)

/usr/bin/env bash << 'EOF'
SCRIPT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/tlg}/scripts/tg-cli.py"

# Send a photo/image (auto-detected)
uv run --python 3.13 "$SCRIPT" send-file @username /path/to/photo.jpg

# Send with caption
uv run --python 3.13 "$SCRIPT" send-file -1003958083153 /path/to/image.png -c "Check this out"

# Force send as document (no preview)
uv run --python 3.13 "$SCRIPT" send-file @username /path/to/image.png --document
EOF

Usage: Direct Telethon (preferred for HTML captions and multi-file sends)

When you need HTML-formatted captions or need to send multiple files in sequence, bypass tg-cli.py and use Telethon directly. This pattern was proven reliable:

VIRTUAL_ENV="" uv run --python 3.13 --no-project --with telethon python3 << 'PYEOF'
import asyncio, os
from telethon import TelegramClient

SESSION = os.path.expanduser("~/.local/share/telethon/eon")
API_ID = 18256514
API_HASH = "4b812166a74fbd4eaadf5c4c1c855926"
CHAT_ID = -1003958083153  # negative for groups

CAPTION = """<b>File Title</b>

<pre>
- Item one
- Item two
- Item three
</pre>"""

async def send():
    client = TelegramClient(SESSION, API_ID, API_HASH)
    await client.connect()

    # Single file with HTML caption
    await client.send_file(CHAT_ID, "/path/to/file.md",
                           caption=CAPTION, parse_mode='html')

    # Multiple files in sequence
    files = ["/path/to/file1.md", "/path/to/file2.md"]
    captions = ["<b>First file</b>", "<b>Second file</b>"]
    for f, c in zip(files, captions):
        await client.send_file(CHAT_ID, f, caption=c, parse_mode='html')

    print("All files sent.")
    await client.disconnect()

asyncio.run(send())
PYEOF

Parameters (tg-cli.py)

| Parameter | Type | Description | | -------------- | ---------- | -------------------------------------- | | recipient | string/int | Username, phone, or chat ID | | file | path | Local file path | | -c/--caption | string | Caption text (plain text only via CLI) | | --voice | flag | Send as voice note | | --video-note | flag | Send as round video | | --document | flag | Force document (no media preview) |

Supported Formats

Telethon auto-detects media type by extension. Override with flags.

| Type | Extensions | Notes | | -------- | ----------------- | ------------------------------------ | | Photo | jpg, png, webp | Compressed by Telegram | | Video | mp4, mov, avi | Use --document to skip compression | | Audio | mp3, m4a, flac | Sent as audio player | | Voice | ogg (opus) | Requires --voice flag | | Document | pdf, zip, md, any | Sent as file attachment |

Anti-Patterns (NEVER DO)

| Anti-Pattern | Why It Fails | | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | | Running uv run without VIRTUAL_ENV="" when using inline python | Broken .venv in cwd causes uv to fail even with --no-project | | Using tg-cli.py send-file with HTML in -c caption | CLI caption is plain text — use direct Telethon for parse_mode='html' | | Checking only session file existence in preflight | Session file can exist but be expired — must check is_user_authorized() |

Post-Execution Reflection

After this skill completes, check before closing:

Did the command succeed? — If not, fix the instruction or error table that caused the failure.
Did parameters or output change? — If tg-cli.py's interface drifted, update Usage examples and Parameters table to match.
Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Agent Skills: Send Media on Telegram

Install this agent skill to your local

Skill Files