connect-telegram

name

connect-telegram

description

Step-by-step guided setup to connect this workspace to Telegram so the user can talk to and control Claude Code from their phone via a Telegram bot. Use this skill whenever the user wants to set up Telegram, create a Telegram bot, pair a bot with this workspace, control Claude Code remotely from chat, "talk to this project from my phone", or mentions BotFather, the telegram plugin, channels, or pairing codes. Trigger it even if the user only says something like "connect telegram" or "let me chat with this workspace".

Connect this workspace to Telegram

Guide the user, one step at a time, through connecting this workspace to a Telegram bot so they can send messages to Claude Code and get work done from their phone. Assume the user may not be technical. Explain each step in plain language, do the parts you can do from the shell yourself, hand over the parts that need an interactive terminal, and wait for the user to confirm each step before moving on.

This guide is based on the official plugin at anthropics/claude-plugins-official (external_plugins/telegram). When in doubt about a command, that repo's README.md and the plugin's own skills/configure and skills/access are the source of truth. Verified working against Claude Code CLI 2.1.126 and telegram plugin 0.0.6.

Critical environment note (read first)

The Telegram plugin's slash commands (/plugin, /telegram:configure, /telegram:access, /reload-plugins) only work in an interactive terminal Claude Code session (you ran claude in a terminal and are typing at the prompt). In a non-interactive session, such as the Claude Code desktop app's side panel or an SDK/-p run, those commands fail with a message like "/plugin isn't available in this environment."

So there are two tracks, and you should use whichever fits the user's session:

• Shell/CLI track (works anywhere, including non-interactive): install the plugin, install Bun, and set the token by running shell commands and the claude plugin ... subcommands directly. You (Claude) can do these via Bash.
• Interactive track (terminal only): launching the channel server with --channels, and pairing/locking access. The user must do these in a real terminal. There is no non-interactive substitute for pairing.

Detect the situation: if the user reports "/plugin isn't available in this environment", switch that step to the shell/CLI track.

Platform note (macOS, Linux, Windows)

The commands below use a Unix shell (bash/zsh) and Unix paths (~/.claude/...), which cover macOS, Linux, and Windows Subsystem for Linux (WSL). If the user is on Windows, read references/windows.md and use its commands:

• Simplest: WSL2. Run claude inside a WSL (Ubuntu) shell and every command here works verbatim, including the plugin's own bash-based commands. Recommended on Windows.
• Native Windows (PowerShell): references/windows.md gives the PowerShell equivalent of every shell step (install Bun, write the token, launch, alias, API key). The token file becomes %USERPROFILE%\.claude\channels\telegram\.env.

Ask which the user is on if it is not obvious, then follow the matching commands.

Prerequisites

Confirm with the user in one short message:

1. Telegram app installed and an account (phone or desktop).
2. Access to a terminal where they can run claude interactively. This is required. Pairing and the channel server launch cannot be done from a non-interactive panel.
3. Bun is installed (the plugin's channel server runs on Bun).
   • macOS / Linux / WSL: check with command -v bun; if missing, install with curl -fsSL https://bun.sh/install | bash (adds ~/.bun/bin to the shell profile). After install, a fresh terminal has bun on PATH.
   • Windows (PowerShell): check with Get-Command bun; if missing, install with powershell -c "irm bun.sh/install.ps1 | iex", then open a new terminal so bun is on PATH. See references/windows.md.

Phase 1 - Create a Telegram bot (user acts in Telegram)

Who does what: the user does all of this in the Telegram app.

1. Open Telegram, search for BotFather (official, blue verified check), open the chat.
2. Send /newbot.
3. Enter a display name (anything, e.g. "My Workspace Bot").
4. Enter a username that is unique and ends in bot (e.g. my_workspace_bot). If taken, BotFather asks again.
5. BotFather replies with an API token like 123456789:AAExampletokenstringGoesHere. Copy it.

Security note to relay: the token is the bot's password. Do not post it publicly, paste it into a shared chat, or commit it to git. The plugin stores it outside the project at ~/.claude/channels/telegram/.env (chmod 600), which is the correct secure location.

Checkpoint: get the token from the user. They can paste it (you will use it once in the configure step and not repeat it elsewhere) or keep it private and you hand them placeholders.

Phase 2 - Install the plugin and set the token

Who does what: prefer the shell/CLI track so this works in any session.

Install the plugin.

• Interactive track (terminal): /plugin install telegram@claude-plugins-official then /reload-plugins.
• Shell/CLI track (works anywhere): run claude plugin install telegram@claude-plugins-official. Confirm with claude plugin list that it shows telegram@claude-plugins-official and Status: enabled. The claude-plugins-official marketplace is usually already configured; if not, add it with claude plugin marketplace add anthropics/claude-plugins-official first.

Set the bot token.

• Interactive track: /telegram:configure <your-token>.
• Shell/CLI track (equivalent to what /telegram:configure does): write the token to the plugin's env file yourself:

  mkdir -p ~/.claude/channels/telegram
  printf 'TELEGRAM_BOT_TOKEN=%s\n' '<your-token>' > ~/.claude/channels/telegram/.env
  chmod 600 ~/.claude/channels/telegram/.env
  

  (No quotes around the token value. chmod 600 because it is a credential.) If the user shared the token, fill it in; otherwise use the <your-token> placeholder. Verify without printing the secret, e.g. show only the first 10 chars.
• Windows (PowerShell): do the equivalent write per references/windows.md (path %USERPROFILE%\.claude\channels\telegram\.env, written with [System.IO.File]::WriteAllText(... "\n") to avoid BOM/CRLF that would corrupt the token).

Note: the channel server reads .env once at boot, so a token change needs a restart of the --channels session (or /reload-plugins in an interactive session).

Checkpoint: plugin enabled, token file present with 600 perms.

Phase 3 - Launch the channel server (interactive terminal, user runs it)

Who does what: the user runs this in a terminal. There is no non-interactive substitute. The --channels flag is registered by the plugin, so it will NOT appear in claude --help until the plugin is installed, and the server "won't connect without this flag."

Have the user, in a terminal:

1. Change into this workspace so Telegram is bound to it (use the directory this skill lives in; substitute the real path): cd "<path-to-this-workspace>"
2. Launch with channels enabled: claude --channels plugin:telegram@claude-plugins-official

Choosing the model: add --model to this launch to pick which model serves Telegram, e.g. --model claude-opus-4-8 (Opus 4.8) or --model claude-fable-5 (Fable 5). See "Switching models" below for the full list and how to change it later. The model cannot be switched from a Telegram message.

If launch fails with a Bun error, Bun is not on PATH: open a fresh terminal (macOS/Linux/WSL: so .zshrc/.bun is sourced; Windows: so the updated user PATH is loaded) or install Bun per Prerequisites, then retry. On Windows the cd path uses Windows form, e.g. cd "C:\path\to\your\workspace".

Checkpoint: the session starts and reports the Telegram channel connected.

Phase 4 - Get the user onto the allowlist (Telegram user ID)

Who does what: the user acts in Telegram, then runs a slash command in the --channels session from Phase 3. Both routes below add the user's Telegram user ID (an opaque numeric ID that identifies their account) to the allowlist. Ask the user which route they prefer; default to Route A.

Route A - Pairing (simplest; captures the ID automatically)

1. In Telegram, open the bot (its username from Phase 1) and send any message (e.g. "hi").
2. The bot replies with a 6-character pairing code. Ask the user to copy it and paste it back to you.
3. In the interactive --channels session, run: /telegram:access pair <code> (fill in the code if the user pasted it). This looks up the code and adds the user's Telegram user ID to the allowlist for you.

Codes are one-time and short-lived. If it fails as expired, DM the bot again for a fresh code and retry.

Route B - Add your Telegram user ID directly

Use this if the user wants to enter their ID explicitly, or to add other people.

First, find the Telegram user ID (walk the user through this):

1. In Telegram, search for @userinfobot and open the chat.
2. Press Start (or send it any message).
3. It replies with the account details, including a line like Id: 123456789. That number is the Telegram user ID.
4. Ask the user to copy that number and paste it back to you.

Then add it to the allowlist in the interactive --channels session:

/telegram:access allow <user-id>

For example /telegram:access allow 123456789. Repeat with each person's ID to allow more than one account.

Checkpoint: confirm the user's ID is on the allowlist by running /telegram:access with no arguments; it lists everyone in allowFrom.

Phase 5 - Lock it down to just this user

Who does what: one slash command in the interactive session.

Explain: pairing mode is only a temporary way to capture user IDs. Once the user is paired, switch to allowlist so nobody else can trigger pairing codes or reach the assistant. Recommend this strongly.

Run: /telegram:access policy allowlist

access.json is re-read on every inbound message, so this takes effect immediately, no restart needed. To add someone later: have them DM the bot and approve with /telegram:access pair <code>, or add their numeric ID directly with /telegram:access allow <user-id> (their ID comes from @userinfobot, per Phase 4 Route B). Remove someone with /telegram:access remove <user-id>. See references/troubleshooting.md under "Managing who has access".

Checkpoint: policy is allowlist.

Phase 6 - Test end to end

Have the user DM the bot a real request, e.g. "list the files in this workspace". Confirm Claude Code replies through Telegram with correct content. When that works, setup is complete.

Wrap up:

• Telegram works only while a claude --channels plugin:telegram@... session is running in this workspace. After a reboot or closing that terminal, relaunch it (Phase 3). Offer a launch shortcut: macOS/Linux/WSL shell alias alias claude-tg='claude --channels plugin:telegram@claude-plugins-official'; on Windows PowerShell, a $PROFILE function (see references/windows.md).
• If the token ever leaks: revoke it in BotFather with /revoke, then rewrite ~/.claude/channels/telegram/.env with the new token and restart the session.

Switching models (Opus 4.8, Fable 5, and others)

The model is set by the terminal session that serves Telegram. It cannot be changed from a Telegram message: the bot forwards messages as prompts, so a /model typed on the phone is treated as plain text, not a command. Two ways to choose or change it:

1. At launch, with --model (applies to the whole session):

   claude --channels plugin:telegram@claude-plugins-official --model claude-opus-4-8
   

2. Mid-session, type /model <name> in the terminal running the session (not in Telegram). The change applies to messages arriving over Telegram from then on. To switch models you otherwise relaunch with a different --model.

Model names - use the exact ID to pin a specific version, or the alias to track the latest of that family:

Model	Exact ID (pins the version)	Alias (tracks latest)
Opus 4.8	claude-opus-4-8	opus
Fable 5	claude-fable-5	fable
Sonnet 5	claude-sonnet-5	sonnet
Haiku 4.5	claude-haiku-4-5-20251001	haiku

Examples:

• Opus 4.8 bot: claude --channels plugin:telegram@claude-plugins-official --model claude-opus-4-8
• Fable 5 bot: claude --channels plugin:telegram@claude-plugins-official --model claude-fable-5

Notes:

• Which models are available and how much you can use depend on your Claude Code auth (subscription plan or API key), not on the plugin.
• Check the active model any time by typing /model (no argument) in the session running the channel.

Quick command reference

Step	Where	Command
New bot	Telegram / BotFather	/newbot
Install Bun (if missing)	Terminal	`curl -fsSL https://bun.sh/install
Install plugin (interactive)	Claude Code	/plugin install telegram@claude-plugins-official then /reload-plugins
Install plugin (shell/CLI)	Terminal	claude plugin install telegram@claude-plugins-official
Set token (interactive)	Claude Code	/telegram:configure <your-token>
Set token (shell/CLI)	Terminal	write TELEGRAM_BOT_TOKEN=<token> to ~/.claude/channels/telegram/.env (chmod 600)
Launch channel server	Terminal (in workspace)	claude --channels plugin:telegram@claude-plugins-official
Launch on a specific model	Terminal (in workspace)	claude --channels plugin:telegram@claude-plugins-official --model claude-opus-4-8 (or --model claude-fable-5)
Switch model mid-session	Terminal session (not Telegram)	/model <name> e.g. /model claude-opus-4-8
Pair account	Interactive session	/telegram:access pair <code>
Find your Telegram user ID	Telegram	DM @userinfobot; it replies Id: <number>
Allow a user ID	Interactive session	/telegram:access allow <user-id>
Remove a user ID	Interactive session	/telegram:access remove <user-id>
Check who is allowed	Interactive session	/telegram:access (no args)
Restrict access	Interactive session	/telegram:access policy allowlist

If any step misbehaves, read references/troubleshooting.md for symptom-based fixes before improvising.