Lucklyric avatar

telegram-notifier

Telegram bridge for Claude Code: notification hooks plus on-demand artifact sending via the telegram skill. Triggers: 'use asun:telegram to send', 'telegram this file'. Supports images, video, audio, documents, voice notes, animations, stickers, and text. Configurable via environment variables with dry-run mode.

GitHub stars
30

Install

/plugin install telegram-notifier@cc-dev-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Lucklyric/cc-dev-tools.

Contents

Discovered from source

Skills 1

Telegram: Send Artifacts to the User's Channel

Use the configured Telegram bot to push files or text messages to the user's chat. The same CC_TELEGRAM_BOT_TOKEN / CC_TELEGRAM_CHAT_ID that power the notification hooks also drive this skill — no extra setup.

When to use

Trigger on phrases that explicitly mention Telegram as the destination:

  • "use asun:telegram to send "
  • "telegram this PDF / image / video"
  • "send to telegram"
  • "post to my telegram"
  • "share these artifacts via telegram"

Do NOT trigger when the user just mentions Telegram in passing (e.g., "the telegram bot is working"). Trigger only when Telegram is the requested destination for a specific artifact or message.

How to call the helper

$CLAUDE_PLUGIN_ROOT/scripts/send-artifact.sh [--caption "<text>"] [--type <endpoint>] <file-path>
$CLAUDE_PLUGIN_ROOT/scripts/send-artifact.sh --text "<message>"

The helper auto-detects the right Telegram endpoint from the file extension and falls back to sendDocument for anything unknown, so a single call works for most files.

File path resolution

  1. If the user gives an absolute path, use it as-is.
  2. If the user gives a relative path or a bare filename, resolve against $PWD first.
  3. If the file doesn't exist at the resolved path, list candidate matches via find . -maxdepth 3 -iname "<basename>" and ask the user to confirm before sending.
  4. Never invent a path. If you cannot find the file, say so.

Extension → endpoint mapping

ExtensionEndpointNotes
.jpg .jpeg .png .webpsendPhotoInline preview in Telegram. 10MB limit.
.gifsendAnimationAnimated, no audio.
.mp4 .mov .mkv .webmsendVideoUp to 50MB via bot API.
.mp3 .m4a .aac .flac .wavsendAudioMusic-style player.
.ogg .opussendVoiceVoice-note style.
.tgssendStickerTelegram animated sticker format.
anything elsesendDocumentGeneric file, filename preserved, up to 50MB.

Override with --type <endpoint> if the auto-detection picks the wrong one (e.g., .gif you want as a static image: --type document).

Caption handling

  • The helper always prepends a [hostname:project] tag so the user can see which session sent the file.
  • If the user supplies extra text ("send foo.pdf with note: this is the v2 draft"), pass it via --caption "this is the v2 draft".
  • If the user does not supply a note, omit --caption — the tag alone is sent.
  • Stickers, voice notes, and video notes do not accept captions; the helper drops the caption silently for those endpoints.

Multiple files

Telegram's bot API has no batch upload for arbitrary documents, so loop one call per file. Surface successes and failures per file:

for f in report.pdf chart.png notes.md; do
    $CLAUDE_PLUGIN_ROOT/scripts/send-artifact.sh --caption "v2 review pack" "$f" || echo "failed: $f"
done

For an image album (multiple photos in one Telegram message), the bot API supports sendMediaGroup — not implemented in v0.4.0. If the user asks for an album, send individually and note the limitation.

Size limits

EndpointLimit
sendPhoto10 MB
sendDocument and most others50 MB
Local Bot API serverup to 2 GB (not configured by default)

If a file exceeds the limit, the API returns an error; surface it verbatim. Common workaround: tar/zip the file, or split, then resend.

Error handling

The helper exits non-zero on every failure with a clear stderr message:

ExitMeaning
2Usage error (bad flags, missing file arg). Recheck the invocation.
3File not readable. Confirm path with the user.
4CC_TELEGRAM_BOT_TOKEN or CC_TELEGRAM_CHAT_ID not set. Ask the user to export them.
5Telegram API returned an error. Surface the API response so the user sees the reason (often size limit, wrong file type for endpoint, or auth issue).

Always surface the helper's output verbatim — do not paraphrase API errors.

Dry-run

Set CC_TELEGRAM_DRY_RUN=true to print the planned call without hitting the API. Useful for verifying which endpoint will be chosen before actually sending.

Reference index

  • scripts/send-artifact.sh — the helper script (single file, fully self-contained).
  • hooks/notify.sh — the legacy notification helper, unchanged.
  • hooks/hooks.json — Stop / SubagentStop / Notification hook definitions, unchanged.

Sponsors

Details

Marketplace
Lucklyric/cc-dev-tools
Source
plugins/telegram-notifier
Category
Community

More from Lucklyric/cc-dev-tools

All 4