pi-telegram

One-way Telegram notifications for Pi agents.

This package gives Pi Telegram tools and a telegram-notify skill so you can say things like:

When you're done with the job, send me a report via Telegram.

The integration is intentionally agent → Telegram only. It does not listen for Telegram replies, run a webhook, or turn Telegram into a second Pi chat thread.

Install

Install from npm:

pi install npm:@wienerberliner/pi-telegram

Or try the local checkout while developing:

pi install /path/to/pi-telegram

For local development in this repository, .pi/settings.json loads the package root (..) after the project is trusted. Run /trust and /reload if Pi is already open.

Setup

1. In Telegram, open @BotFather and create a bot with /newbot.

2. Copy the bot token.

3. In Pi, run:

   /setup-telegram-token
   

4. Paste the BotFather token into the secure Pi input prompt. This keeps the token out of the LLM chat transcript.

5. The command validates the token, saves it to a global Pi Telegram config file, and asks you to send a message such as hello world to the bot.

6. After you send the Telegram message, press Enter in Pi. The command fetches the chat id with Telegram getUpdates, saves it globally, and sends a confirmation message to Telegram.

The generated global config lives at:

~/.pi/agent/pi-telegram/.env

It uses:

PI_TELEGRAM_BOT_TOKEN=123456:your-bot-token
PI_TELEGRAM_CHAT_ID=123456789

The extension automatically reads the global config from ~/.pi/agent/pi-telegram/.env, so all Pi sessions can use the same Telegram setup. A project-local .env in Pi's current working directory can override the global config for that project. Real environment variables override both, and the unprefixed names TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are supported.

Usage

Ask Pi naturally:

Run the test suite. When you're done, send me a report via Telegram.

Send screenshots/final.png to me via Telegram with caption "Final screenshot".

Send output/demo.m4a to Telegram as the demo audio.

Build the Android debug APK and send it to me via Telegram.

CLI

The package also installs a pi-telegram command for shell scripts, other agents, or contexts where loading Pi tools is not desirable.

pi-telegram send-message --message "Build finished" --silent
pi-telegram send-message --message-file ./report.txt --json
pi-telegram send-file --source ./app-release.apk --caption "Release APK" --json
pi-telegram send-image --source ./screenshot.png --caption "Final screenshot"
pi-telegram send-audio --source ./demo.m4a --title "Demo audio"
pi-telegram setup --bot-token-file ~/.secrets/pi-telegram-token --chat-id 123456789
printf '%s' "$BOT_TOKEN" | pi-telegram setup --bot-token-stdin --chat-id 123456789
pi-telegram config-path

CLI commands read the same configuration as the Pi extension:

1. Real environment variables.
2. Project-local .env in the current working directory.
3. Global ~/.pi/agent/pi-telegram/.env.

Run pi-telegram --help for the full command list and options. The CLI also supports --dry-run for validation without sending.

When installed from npm, the package tries to create a convenience symlink at ~/.local/bin/pi-telegram. It will not overwrite an existing non-pi-telegram command at that path. If ~/.local/bin is not on your shell PATH, either add it or call the installed CLI directly with node ~/.pi/agent/npm/node_modules/@wienerberliner/pi-telegram/bin/pi-telegram.mjs ....

Tools

telegram_send_message

Sends text to Telegram using the Bot API sendMessage method.

Parameters:

• message — text to send. Long messages are split into Telegram-sized chunks.
• chat_id — optional override for the configured chat id or @channelusername.
• parse_mode — optional HTML, MarkdownV2, or Markdown; omit for plain text.
• disable_notification — optional silent delivery.

telegram_send_image

Sends an image/photo using the Bot API sendPhoto method.

Parameters:

• source — local image path, absolute image path, HTTP(S) URL, or Telegram file_id.
• caption — optional caption, max 1024 characters.
• chat_id, parse_mode, disable_notification — same as text messages.

Local image files are uploaded with multipart/form-data. Telegram's sendPhoto limit is 10 MB.

telegram_send_file

Sends a general file/document using the Bot API sendDocument method. This is useful for Android APKs/AABs, logs, test reports, ZIPs, PDFs, and other build artifacts.

Parameters:

• source — local file path, absolute file path, HTTP(S) URL, or Telegram file_id.
• caption — optional caption, max 1024 characters.
• filename — optional display filename for local file uploads.
• disable_content_type_detection — optional; disables Telegram's server-side content type detection for uploaded files.
• chat_id, parse_mode, disable_notification — same as text messages.

Local files are uploaded with multipart/form-data. Telegram's public Bot API currently allows documents up to 50 MB. Sending documents by HTTP URL is more limited; prefer local file paths for arbitrary artifacts.

telegram_send_audio

Sends an audio file using the Bot API sendAudio method.

Parameters:

• source — local audio path, absolute audio path, HTTP(S) URL, or Telegram file_id.
• caption — optional caption, max 1024 characters.
• title — optional track title.
• performer — optional performer/artist.
• duration — optional duration in seconds.
• chat_id, parse_mode, disable_notification — same as text messages.

Local audio files are uploaded with multipart/form-data. Telegram documents sendAudio for MP3/M4A music-player audio and currently allows files up to 50 MB.

Configuration

Variable	Required	Description
PI_TELEGRAM_BOT_TOKEN / TELEGRAM_BOT_TOKEN	yes	Bot token from BotFather.
PI_TELEGRAM_CHAT_ID / TELEGRAM_CHAT_ID	yes by default	Target chat id. Can be overridden per tool call with chat_id.
PI_TELEGRAM_API_BASE / TELEGRAM_API_BASE	no	Defaults to https://api.telegram.org.
PI_TELEGRAM_CONFIG_DIR	no	Directory for the global Telegram .env. Defaults to ~/.pi/agent/pi-telegram.

Configuration precedence is: real environment variables, then project-local .env, then global ~/.pi/agent/pi-telegram/.env.

npm

Package page: https://www.npmjs.com/package/@wienerberliner/pi-telegram