Telegram bot setup — your agent's voice in your pocket

Email is where reports go; Telegram is where an agent talks to you. Instant, free, works on every device, and a bot takes five minutes to create. This is the channel an always-on agent uses to say "build finished," "revenue moved," or "something needs you" — and the same pipeline as /agent-proactive-email, just a different last mile.

trigger  →  agent writes the message  →  Telegram bot delivers it to your phone

Step 1 — Create the bot with @BotFather (5 minutes)

BotFather is Telegram's official bot for making bots.

1. In Telegram, search @BotFather (blue checkmark) and open it.
2. Send /newbot.
3. It asks for a name — the display name, anything: Keys Ops.
4. It asks for a username — must end in bot: keys_ops_bot.
5. BotFather replies with your bot token — a string shaped like 1234567890:AAxxxx.... This token IS the bot. Anyone holding it can send and read as your bot.

Token rules (non-negotiable): - It goes in an environment file, never in code, never in a repo, never in a crontab line. - If it ever touches a repo or a chat log, revoke it immediately: BotFather → /revoke → new token. Rotation takes ten seconds; a leaked bot is forever.

Step 2 — Get your chat ID

A bot cannot message you until you message it first (Telegram's anti-spam rule).

1. Open your new bot (BotFather gave you a t.me/your_bot link) and press Start.
2. Then ask the API who wrote in:

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates" | python3 -m json.tool

Look for "chat": {"id": 123456789, ...} — that number is your chat ID.

Step 3 — First message

export TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_HERE   # keyzhub-allow placeholder
export TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE       # keyzhub-allow placeholder

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
  -d chat_id="$TELEGRAM_CHAT_ID" -d text="The bot is alive."

Success looks like: the message arrives on your phone, and the response JSON says "ok": true.

Step 4 — Wire it to your agent

examples/send_telegram.py in this repo is a stdlib-only sender — same design as the email version (env-driven, refuses empty messages, rate-limit guard):

claude -p "Read progress.md and write a 4-line status update. No preamble." \
  | python3 examples/send_telegram.py

Put that line on a schedule (cron / launchd — see /agent-proactive-email Step 3, identical mechanics) and your agent reports to your pocket every morning.

examples/telegram.env.example is the env template — copy to ~/.telegram-bot.env, fill it in, and source it from your cron script.

Step 5 — Going further

• Two-way (you text the bot, the agent answers): that's a polling/webhook loop — the ready-made road is OpenClaw, which speaks Telegram natively; point its onboarding at the same BotFather token.
• Groups: add the bot to a group and the group's chat ID (a negative number, from the same getUpdates call) becomes the target — one bot briefing a team.
• Formatting: add -d parse_mode=Markdown to sendMessage for bold/code in alerts.

Rules

1. The token is a secret with a body count. Env file, /revoke on any doubt.
2. One bot per job beats one bot for everything — a leak or revoke then only takes down one pipe.
3. Rate-limit by design — the example sender enforces a gap so a misfiring trigger can't machine-gun your phone (Telegram will also throttle you).
4. Message yourself first, same as email: run it solo before any group sees it.

Part of KeyzHub — take the code, build your own. Siblings: /agent-proactive-email (email channel), /ai-agents-setup (the agents themselves).