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):
bun "$SCRIPT" check-auth
If EXPIRED, run /tlg:setup first (uses 3-step non-interactive auth pattern).
Usage: tg-cli.ts (simple cases)
/usr/bin/env bash << 'EOF'
ROOT="$(cc-plugin-root tlg)"
SCRIPT="$ROOT/scripts/tg-cli.ts"
# Send a photo/image (auto-detected)
bun "$SCRIPT" send-file @username /path/to/photo.jpg
# Send with caption (plain text only)
bun "$SCRIPT" send-file -1003958083153 /path/to/image.png -c "Check this out"
# Force send as document (no preview)
bun "$SCRIPT" send-file @username /path/to/image.png --document
# Send voice note
bun "$SCRIPT" send-file -1003958083153 /path/to/audio.ogg --voice
# Send round video
bun "$SCRIPT" send-file @username /path/to/video.mp4 --video-note
EOF
Known limitation: captions via CLI are plain text only (no HTML). For formatted captions, use the draft skill to compose a message in Saved Messages, copy it into the target chat, and manually attach the file there.
Parameters (tg-cli.ts)
| 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
GramJS 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 bun "$SCRIPT" without checking auth first |
If session expired, auth will fail |
Using formatted text in -c caption |
CLI caption is plain text only — use draft skill for formatted captions |
| Checking only session file existence in preflight |
Session file can exist but be expired — must check with check-auth |
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.ts'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.
1---
2name: send-media
3description: "Use when user wants to send or upload a file, photo, video, voice note, or document on Telegram via their personal account."
4allowed-tools: Bash, Read, Grep, Glob
5metadata:
6 source: https://skillmd.com/skills/terrylica/send-media
7---
8
9# Send Media on Telegram
10
11Send files, photos, videos, voice notes, and documents from your personal Telegram account.
12
13> **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.
14
15## Preflight
16
17Check session is **authorized** (not just that the file exists):
18
19```bash
20bun "$SCRIPT" check-auth
21```
22
23If `EXPIRED`, run `/tlg:setup` first (uses 3-step non-interactive auth pattern).
24
25## Usage: tg-cli.ts (simple cases)
26
27```bash
28/usr/bin/env bash << 'EOF'
29ROOT="$(cc-plugin-root tlg)"
30SCRIPT="$ROOT/scripts/tg-cli.ts"
31
32# Send a photo/image (auto-detected)
33bun "$SCRIPT" send-file @username /path/to/photo.jpg
34
35# Send with caption (plain text only)
36bun "$SCRIPT" send-file -1003958083153 /path/to/image.png -c "Check this out"
37
38# Force send as document (no preview)
39bun "$SCRIPT" send-file @username /path/to/image.png --document
40
41# Send voice note
42bun "$SCRIPT" send-file -1003958083153 /path/to/audio.ogg --voice
43
44# Send round video
45bun "$SCRIPT" send-file @username /path/to/video.mp4 --video-note
46EOF
47```
48
49**Known limitation**: captions via CLI are plain text only (no HTML). For formatted captions, use the `draft` skill to compose a message in Saved Messages, copy it into the target chat, and manually attach the file there.
50
51## Parameters (tg-cli.ts)
52
53| Parameter | Type | Description |
54| -------------- | ---------- | -------------------------------------- |
55| recipient | string/int | Username, phone, or chat ID |
56| file | path | Local file path |
57| `-c/--caption` | string | Caption text (plain text only via CLI) |
58| `--voice` | flag | Send as voice note |
59| `--video-note` | flag | Send as round video |
60| `--document` | flag | Force document (no media preview) |
61
62## Supported Formats
63
64GramJS auto-detects media type by extension. Override with flags.
65
66| Type | Extensions | Notes |
67| -------- | ----------------- | ------------------------------------ |
68| Photo | jpg, png, webp | Compressed by Telegram |
69| Video | mp4, mov, avi | Use `--document` to skip compression |
70| Audio | mp3, m4a, flac | Sent as audio player |
71| Voice | ogg (opus) | Requires `--voice` flag |
72| Document | pdf, zip, md, any | Sent as file attachment |
73
74## Anti-Patterns (NEVER DO)
75
76| Anti-Pattern | Why It Fails |
77| --------------------------------------------------- | ------------------------------------------------------------------------- |
78| Running `bun "$SCRIPT"` without checking auth first | If session expired, auth will fail |
79| Using formatted text in `-c` caption | CLI caption is plain text only — use `draft` skill for formatted captions |
80| Checking only session file existence in preflight | Session file can exist but be expired — must check with `check-auth` |
81
82## Post-Execution Reflection
83
84After this skill completes, check before closing:
85
861. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
872. **Did parameters or output change?** — If tg-cli.ts's interface drifted, update Usage examples and Parameters table to match.
883. **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.
89
90Only update if the issue is real and reproducible — not speculative.