Claude Code Telegram Channels: Setup and Troubleshooting

Introduction

I just spent an evening getting Telegram working as a channel in Claude Code. If you want the backstory on why Telegram is the developer platform of choice over WhatsApp, we wrote a separate piece on that. The feature itself is great. Text your bot a message, it lands in your Claude Code session, Claude acts on it, replies back to Telegram. Bug reports become instant fixes. Deployment commands go from your pocket to production.

But the setup had friction. The kind of friction where the plugin loads, says "1 MCP server," and then silently fails. No error in the terminal. No logs to check. Just nothing.

I figured it out. Here's the full walkthrough — including every problem I hit and how to fix each one. If you're new to Claude Code, start with our complete guide to Claude Code first, then come back here.

Connect a bot to one intended session

The bot is a bridge into a running Claude Code session. Messages can reach the files and tools that session is permitted to use. Verify the project directory and user allowlist before sending work requests.

claude --channels plugin:telegram@claude-plugins-official

Configure the bot first, then start the enabled session and pair the intended sender. Keep additional remote interfaces separate until this exchange works.

Check the installed version and account access

Use a current Claude Code installation and verify claude --version and bun --version. The supported channel plugins use Bun. Confirm channel availability for your authentication route and organization settings in the official channel guide.

Create a dedicated Telegram bot and keep its token private. Work in a project with appropriate tool permissions, since a chat message can reach a session that can edit files and run commands.

Step 1: Create the Telegram bot

Open Telegram on your phone and search for @BotFather. Start a conversation and send:

/newbot

BotFather walks you through naming your bot. Pick whatever you want. The name doesn't affect functionality. The username must end in "bot" (e.g., my_claude_bot). When it's done, you get a token that looks like this:

123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy that token. You'll need it in Step 3.

Step 2: Install the Telegram plugin

Inside a Claude Code session, run these two commands:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install telegram@claude-plugins-official

The first adds the official plugin marketplace. The second installs the Telegram channel from it. You'll see output confirming the install.

If either command fails, check your Claude Code version. Both require v2.1.81 or later. Our development environment setup guide walks through getting Claude Code installed from scratch if you need it.

Configure the bot token

After creating the bot and installing the official Telegram plugin, use its configure command:

/telegram:configure <token>

Replace the token locally with the value supplied by BotFather. Do not put it into the repository, a screenshot or a public issue. The plugin documentation describes its credential storage and supported environment-variable alternative.

Start the channel, then pair your account

Restart Claude Code with the channel enabled before messaging the bot:

claude --channels plugin:telegram@claude-plugins-official

Send the bot a message in Telegram. Use the returned pairing code in the running Claude Code session, then restrict access:

/telegram:access pair <code>
/telegram:access policy allowlist

Confirm that your account can communicate and an unapproved account cannot. Pairing alone is not a reason to grant broader file or command permissions.

Verify an end-to-end exchange

Send a harmless request, such as asking the assistant to describe the project structure without changing files. Confirm that the message reaches the intended session and that the reply returns to Telegram.

The local session must remain running. If the computer sleeps or the process exits, investigate session availability before changing the bot configuration. Keep Remote Control setup separate until the basic channel works.

If the MCP server fails to start

Check the actual startup error, installed plugin version and Bun availability. Update or reinstall through the supported plugin mechanism when the installed package is incomplete.

Do not make a permanent fix by editing a versioned plugin cache directory. Updates can replace those files, and an old package-specific workaround may no longer apply. Match the error to current troubleshooting documentation and report a reproducible issue without credentials.

If the token is missing

Use the plugin’s supported configure command again and confirm that the session can access the configured credential. Check for a stale environment override or a token rotated in BotFather. Do not paste credentials into logs or commit them to the repository.

Restart the session after correcting configuration and test a harmless message. Treat authentication errors separately from pairing and access-policy errors.

If Telegram reports a polling conflict

Check whether another session or test process is using the same bot token. Identify the specific owner before stopping it; do not terminate unrelated Bun processes. Also check whether a webhook was configured for a different integration.

Telegram supports polling and webhooks as different update mechanisms. Choose one owner for the bot and follow the Telegram update-delivery guidance. Restart the intended session and verify receipt before sending an edit request.

If the bot does not respond

Work through the chain: correct bot account, running host process, plugin startup, token validity, enabled channel and sender access. A silent bot is not proof that one particular configuration file is broken.

Inspect the actual startup and tool errors. Test from the approved sender and confirm the session remains online. Use supported update or reinstall steps for a broken plugin rather than editing its cached code.

If a pairing code is rejected

Request a fresh code from the intended bot and approve it in the correct running session. Check that pairing is currently enabled and that another session is not receiving the updates. After approval, restore the allowlist policy and test both an approved and an unapproved sender.

If a reply is incomplete

Compare the terminal record, delivery tool result and received message. Check plugin errors, formatting, platform length limits and whether a long reply was split. The earlier version attributed all cutoffs to MCP; that diagnosis was not established.

Use a short test message followed by a known long one. For a detailed code review, inspect the full session or a saved artifact rather than relying only on a notification.

The access system explained

The Telegram channel has three access modes:

You should always end up on allowlist. The pairing mode is temporary. It exists so you can capture Telegram user IDs you don't already know. Once everyone is added, lock it.

All access commands:

/telegram:access                    # Show current status
/telegram:access pair <code>        # Approve a pairing code
/telegram:access allow <id>         # Add a sender ID directly
/telegram:access remove <id>        # Remove a sender
/telegram:access policy pairing     # Re-enable pairing (temporary)
/telegram:access policy allowlist   # Lock to allowlist only
/telegram:access policy disabled    # Disable all access

If you need to add someone later: flip to pairing, have them DM the bot, approve their code, flip back to allowlist.

Keep configuration separate from cached code

The plugin’s supported configure command manages its token setup. Review access using its access commands. Treat the plugin cache as installed code, not a stable home for hand-edited credentials or fixes.

Back up only the configuration you are authorized to retain, with appropriate secret handling. If a token is exposed, rotate it through the provider and update the configured value.

Keep the operating dependencies visible

• The host process and computer must remain available.
• The bot token and sender policy control access to the channel.
• Plugin and account availability can change during the research preview.
• A shared bot needs a deliberate update-delivery owner.
• Message delivery needs its own failure checks.

Review session permissions and use the current channel documentation when updating the installation.

A short operating checklist

1. Verify Claude Code and Bun are available.
2. Install the official Telegram plugin.
3. Configure the bot token privately.
4. Start Claude Code with the channel enabled.
5. Pair your account and apply the allowlist policy.
6. Test a harmless exchange and review session permissions.
7. Keep one polling owner for the bot and monitor failures.

Use the current channel instructions for exact commands and supported authentication. Read the Remote Control comparison before adding another remote interface.

What it looks like in practice

Once everything is connected, the workflow is simple. You text your bot:

"What's the status of the homepage?"

Claude reads your project, checks the files, and replies in Telegram with the answer. You can send follow-ups:

"Fix the spacing on the hero section and push to main."

Claude makes the changes, commits, pushes, and confirms in the Telegram thread. If you're running Remote Control alongside Channels, you can also see the full session in the Claude app on your phone. That's useful when you want to review a diff before approving a push.

This is the same workflow I use when building full-stack applications with Claude Code. Telegram for quick fire-and-forget commands during the day. Remote Control for the review-and-deploy sessions where I need to see everything.

Bug reports from clients? Forward them to your bot. Feature requests? Same. Quick deployments while you're at lunch? Text the bot. The phone becomes your terminal.

If you're running multiple client projects, server mode with Git worktrees keeps each session isolated so one project's changes never bleed into another.

I build websites and web applications for service businesses and law firms at Luminous Digital Visions. If you want to see what this workflow can do for your next project, message us on WhatsApp.