pi-telegram-bridge

Telegram bot bridge for pi agents — send messages, ask questions, and listen for human replies via Telegram.

Install

pi install npm:@bytesbrains/pi-telegram-bridge

Configuration

Set the following environment variables:

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11"
export TELEGRAM_CHAT_ID="123456789"

Variable	Required	Description
TELEGRAM_BOT_TOKEN	✅	Bot token from @BotFather
TELEGRAM_CHAT_ID	✅	Target chat ID (your personal chat or a group)

Tools

telegram_listen

Check for new inbound messages from the human.

telegram_listen()

telegram_send

Send a one-way message. Use for status updates and progress reports.

telegram_send(message="Build completed successfully ✅")

telegram_ask

Ask a question with inline keyboard options and wait for a human reply. Blocks until answered or timeout (default 30 min).

telegram_ask(question="Deploy to production?")
telegram_ask(question="Which branch?", options=["main", "staging", "dev"])
telegram_ask(question="Approve this change?", options=["Approve", "Reject", "Need changes"], timeoutMinutes=5)

telegram_override

Ask a human to approve or reject a blocked action (force push, destructive git ops, file deletion, etc.). Designed for supervisor override flows. Returns details.action = "proceed"|"abort"|"explain" so the agent can call supervisor_override() or abort.

telegram_override(
  command="git push gitea feat/add-check --force",
  reason="Force push can overwrite remote history"
)

telegram_override(
  command="rm -rf node_modules",
  reason="Recursive deletion outside project boundary",
  context="User requested a clean reinstall of dependencies",
  options=["Yes, it's fine", "No, cancel", "Use npx instead", "Explain more"],
  timeoutMinutes=10
)

Parameters:

Param	Required	Default	Description
command	✅	—	The blocked command or action
reason	✅	—	Why it was blocked by the supervisor
context	❌	—	Additional context (what the user asked for, etc.)
options	❌	["Yes, proceed", "No, cancel", "Explain more"]	Custom button labels
timeoutMinutes	❌	30	How long to wait for a response

Returns details:

Field	Type	Description
choice	string	The exact button label the human clicked
action	string	"proceed" (first option), "abort" (second option), or "explain" (anything else)
command	string	The original blocked command
timedOut	boolean	Whether the request timed out

Agent workflow:

1. Agent gets blocked by supervisor
2. Calls telegram_override(command, reason, context)
3. Checks details.action:
   • "proceed" → call supervisor_override(reason, command)
   • "abort" → tell user action was cancelled
   • "explain" → call telegram_send(message="...") with more context, then re-ask
4. If details.timedOut → abort the action

telegram_status

Check if the bridge is configured and running.

telegram_status()

Background Listener

The extension starts a background listener on session start that polls for incoming Telegram messages. Any non-bot text message in the configured chat is forwarded to the agent as a user message. The agent responds with a confirmation.

The listener runs automatically — no manual setup needed.

How It Works

1. Session start: The bridge restores the last processed update ID from session state and starts polling
2. Inbound messages: Non-bot text messages in the configured chat are forwarded to the agent
3. Session end: The listener stops cleanly on session shutdown
4. Update ID is persisted across sessions to avoid processing duplicate messages

Get a Bot Token

1. Open Telegram and chat with @BotFather
2. Send /newbot and follow the prompts
3. Copy the token and set TELEGRAM_BOT_TOKEN
4. Send a message to your bot, then visit: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
5. Copy the chat.id from the response and set TELEGRAM_CHAT_ID

Requirements

• Node.js >= 18
• A Telegram bot token
• A chat ID to send/receive messages

License

MIT