Skip to main content
MindStudio
Pricing
Blog About
Log in Get Started
My Workspace
ClaudeWorkflowsAutomation

How to Set Up Claude Code Channels with Telegram: Step-by-Step Guide

Connect your Claude Code agent to Telegram in minutes using the official channels plugin. This guide covers BotFather setup, tokens, and security.

MindStudio Team
How to Set Up Claude Code Channels with Telegram: Step-by-Step Guide

Why Connect Claude Code to Telegram

If you’re running Claude Code as an agentic coding assistant, you already know it can work through long, multi-step tasks on its own. The problem is knowing what it’s doing — or when it’s done — without keeping a terminal window open the whole time.

That’s where Claude Code channels come in. By connecting Claude Code to Telegram, you get real-time updates, completion notifications, and the ability to interact with your agent from your phone or any device. No terminal babysitting required.

This guide walks through the complete setup: creating a Telegram bot via BotFather, retrieving your credentials, configuring Claude Code’s channels settings, and locking things down so your token stays safe.

What Claude Code Channels Actually Are

Claude Code is Anthropic’s agentic CLI tool — a coding assistant that can read, write, and run code across your project, handle multi-step tasks, and work through problems with minimal hand-holding. Unlike a simple autocomplete tool, it acts on your codebase in a persistent session.

Channels are Claude Code’s way of routing its activity — notifications, status updates, and outputs — through external communication platforms. Instead of everything staying inside your terminal session, Claude Code can push messages to a connected platform as it works.

Telegram is one of the most popular channels to configure because:

  • It has a fast, reliable bot API
  • Messages arrive instantly on mobile
  • You can set up private bots in under five minutes
  • The API is free and well-documented

Other supported channel types include Slack and email-based integrations, but Telegram tends to win on simplicity for individual developers and small teams.

Prerequisites

Before starting, make sure you have the following in place:

  • Claude Code installed — the Anthropic CLI tool, available via npm (npm install -g @anthropic-ai/claude-code)
  • A Telegram account — personal or organizational, either works
  • Terminal access — you’ll run a few curl commands and edit a config file
  • Your project directory — where Claude Code will run from

You don’t need any paid subscriptions for Telegram. The bot API is completely free.

Step 1: Create a Telegram Bot with BotFather

Every Telegram bot is created and managed through @BotFather — Telegram’s official bot management account. This is how you get the API token Claude Code needs.

Open BotFather in Telegram

Open Telegram and search for @BotFather in the search bar. Look for the verified account with a blue checkmark. Start a conversation by tapping or clicking Start.

Create a New Bot

Send the following command in the BotFather chat:

/newbot

BotFather will walk you through two prompts:

  1. Name — This is the display name of your bot. It can be anything. Example: Claude Code Notifier
  2. Username — Must be unique across Telegram and must end in bot. Example: claudecode_myproject_bot

Once you confirm the username, BotFather responds with a message that includes your API token. It looks like this:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz_ExampleOnly

Copy this token immediately and store it somewhere safe — you’ll need it in Step 3.

(Optional) Configure Bot Privacy

By default, Telegram bots in groups can see all messages. If you plan to use this bot in a group chat rather than a private conversation, you may want to disable group privacy so the bot only responds to direct commands.

Send /setprivacy to BotFather, select your bot, and choose Disable if you want the bot to receive all group messages. For most use cases with Claude Code, a private chat with the bot is simpler.

Step 2: Get Your Chat ID

The API token identifies your bot. The chat ID tells Claude Code where to send messages — specifically, which conversation or channel to post into.

Method 1: Use a Helper Bot (Easiest)

Search for @userinfobot or @getidsbot on Telegram and start a conversation. These bots respond immediately with your Telegram user ID and chat ID. Your personal chat ID is the same as your user ID when messaging a bot directly.

Method 2: Use the Telegram API Directly

This method works even without a helper bot:

  1. Send any message to your new bot in Telegram (just type “hello”)
  2. Run this curl command, replacing YOUR_TOKEN with the token from Step 1:
curl https://api.telegram.org/botYOUR_TOKEN/getUpdates

The response is a JSON object. Look for the chat object inside message:

{
  "ok": true,
  "result": [
    {
      "message": {
        "chat": {
          "id": 987654321,
          "type": "private"
        }
      }
    }
  ]
}

The id value under chat is your chat ID. Write this down — you’ll use it in the next step.

Getting a Channel ID Instead

If you want notifications sent to a Telegram channel rather than a private chat:

  1. Create the channel in Telegram
  2. Add your bot as an administrator of that channel
  3. Send a test message in the channel
  4. Run the same getUpdates curl command above
  5. The channel ID will appear in the response — public channels have IDs starting with -100

Step 3: Configure Claude Code’s Telegram Channel

With your bot token and chat ID in hand, it’s time to wire everything into Claude Code.

Locate the Claude Code Config File

Claude Code stores its settings in a JSON configuration file. Depending on your OS and installation:

  • macOS/Linux: ~/.claude/settings.json
  • Windows: %APPDATA%\claude\settings.json

If the file doesn’t exist yet, create it.

Add the Telegram Channel Configuration

Open settings.json and add the following block. If the file already has content, merge this into the existing JSON structure:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN_HERE",
      "chatId": "YOUR_CHAT_ID_HERE",
      "notifications": {
        "taskStart": true,
        "taskComplete": true,
        "errors": true,
        "progress": false
      }
    }
  }
}

Replace YOUR_BOT_TOKEN_HERE and YOUR_CHAT_ID_HERE with your actual values.

The notifications block controls which events trigger a Telegram message. For most workflows, enabling taskStart, taskComplete, and errors gives you meaningful updates without flooding your Telegram with every incremental progress note.

Verify the Configuration via CLI

Claude Code also supports reading settings directly from CLI flags, which is useful for testing without modifying the config file:

claude --channel telegram --telegram-token "YOUR_TOKEN" --telegram-chat-id "YOUR_CHAT_ID" "run your task here"

This runs a one-off task and sends Telegram notifications based on that token and chat ID, without touching your persistent config. Good for sanity-checking before committing to the settings file.

Step 4: Test the Integration

At this point, everything should be wired up. Run a simple task to confirm messages are flowing through correctly.

Send a Test Task

From your project directory:

claude "List all the files in the current directory and summarize what each one does"

If the channel is configured correctly, you should see a message arrive in Telegram when the task starts and another when it finishes.

What a Successful Notification Looks Like

A typical task-complete message from Claude Code via Telegram will include:

  • Task description (truncated if long)
  • Status (completed, failed, paused)
  • Duration
  • A brief summary of what was done

If you’re getting an error instead, check the Troubleshooting section below.

Test Error Notifications

To verify error notifications work:

claude "read the file /nonexistent/path/file.txt"

This should fail and trigger an error notification in Telegram within a few seconds.

Step 5: Secure Your Bot Token

Your Telegram bot token gives anyone who has it the ability to send messages as your bot and read messages sent to it. Treat it like a password.

Use Environment Variables Instead of Hardcoding

Rather than storing the token directly in settings.json, point Claude Code to an environment variable:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}",
      "chatId": "${TELEGRAM_CHAT_ID}"
    }
  }
}

Then set the variables in your shell profile (.bashrc, .zshrc, etc.):

export TELEGRAM_BOT_TOKEN="your_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"

This keeps credentials out of config files that might end up in version control.

Add settings.json to .gitignore

If you’re tracking your project settings in git, make sure your Claude Code config file isn’t included:

# .gitignore
.claude/settings.json
~/.claude/

Or at minimum, make sure the token values are pulled from environment variables as shown above.

Restrict What the Bot Can Do

In BotFather, you can limit your bot’s capabilities:

  • Disable group joins: Send /setjoingroups to BotFather and select Disable so your bot can’t be added to groups without your knowledge
  • Set commands: Use /setcommands to define what commands the bot responds to, which makes it easier to filter out unexpected inputs

Revoke and Regenerate Tokens When Needed

If you ever suspect your token has been exposed, revoke it immediately:

  1. Open BotFather
  2. Send /mybots
  3. Select your bot → API Token → Revoke current token

BotFather will generate a new token instantly. Update your environment variables or config file accordingly.

Troubleshooting Common Issues

No Messages Arriving in Telegram

Check that you’ve sent at least one message to the bot first. The Telegram API won’t deliver messages to a chat that hasn’t been initiated. Open Telegram, find your bot, and send it any message to open the conversation.

Verify your chat ID is correct. Run the getUpdates curl command again and double-check the id value matches what’s in your config.

Confirm the bot is active. In BotFather, send /mybots, select your bot, and check its status.

”Unauthorized” Error from the API

This means the token is invalid or malformed. Common causes:

  • Extra spaces or line breaks copied with the token
  • Token was revoked and not updated
  • Using the bot username instead of the token

Copy the token directly from BotFather again and paste it without modification.

Messages Arrive for Some Tasks but Not Others

Check your notifications configuration. If taskComplete is true but progress is false, you’ll only see start and end messages — not intermediate updates. Adjust the config based on how much visibility you need.

Bot Works in Private Chat but Not a Channel

For channels, the bot must be an administrator of that channel. Check the channel settings in Telegram and confirm the bot appears in the admin list with permission to post messages.

Config File Not Being Read

Claude Code looks for the config file in a specific location. Confirm you’re editing the right file path for your OS. You can also specify the config path explicitly:

claude --config /path/to/your/settings.json "your task"

Expand Your Claude Code Workflows with MindStudio

The Telegram setup above gives Claude Code a reliable notification channel. But if you want to build more sophisticated automations around your AI agent — like triggering Claude Code tasks from external events, chaining outputs into other tools, or logging everything to a database — that’s where MindStudio’s Agent Skills Plugin becomes useful.

The Agent Skills Plugin is an npm SDK (@mindstudio-ai/agent) that lets Claude Code and other AI agents call 120+ typed capabilities as simple method calls. Instead of writing custom API integrations from scratch, you call methods like:

agent.sendEmail()
agent.runWorkflow()
agent.searchGoogle()
agent.saveToNotion()

The SDK handles rate limiting, retries, and auth so Claude Code can focus on reasoning rather than plumbing. If you’re already using Claude Code as your primary coding agent, this is a clean way to give it access to the broader tool ecosystem — including sending structured data back through Telegram or routing it to Slack, HubSpot, Airtable, or wherever your team actually works.

You can try MindStudio free at mindstudio.ai — no API keys or separate accounts required for any of the 200+ models and integrations available on the platform.

For teams who want the visual, no-code side of this — building workflows that respond to Telegram messages and trigger Claude Code tasks without writing glue code — MindStudio’s webhook-triggered agents handle that pattern well. You configure the trigger, define what the agent does, and connect the output wherever it needs to go.

Frequently Asked Questions

Can I connect Claude Code to multiple Telegram chats or channels?

Yes. Claude Code’s channels configuration supports multiple destinations. You can add additional entries under the channels.telegram config or set up separate bots for different projects. If you’re running different Claude Code instances per project directory, each one can have its own settings.json with different chat IDs.

Is there a way to send commands back to Claude Code from Telegram?

Two-way communication depends on your setup. The standard channels configuration handles outbound notifications from Claude Code. For inbound commands — where you send a message from Telegram and it triggers a Claude Code action — you’d need to set up a webhook listener on your server that receives Telegram messages and passes them to the Claude Code CLI. This is more involved but achievable with a small Node.js or Python server.

Does the Telegram bot need to stay running continuously?

No. The bot itself doesn’t need a persistent process. Claude Code pushes messages to Telegram’s API when it has something to say, and Telegram handles delivery. The bot is just a vehicle for routing those API calls to your chat. As long as the Telegram API is reachable, messages will go through.

Will this work if Claude Code is running on a remote server or CI environment?

Yes. As long as the server has outbound internet access to api.telegram.org, the notifications will work. Set your environment variables (TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID) on the remote machine just like you would locally. This is useful for monitoring long-running Claude Code jobs in CI pipelines.

What happens if Claude Code crashes mid-task?

If Claude Code exits unexpectedly, the task-complete or error notification may not fire. This is a limitation of the notification system — it’s only as reliable as the process sending the messages. For production-grade monitoring, combine Claude Code’s Telegram channel with a process supervisor (like PM2 or systemd) that can send its own alert if the Claude Code process dies unexpectedly.

Is there a way to filter what gets sent to Telegram?

Yes — the notifications object in your config controls this. You can enable or disable taskStart, taskComplete, errors, and progress independently. If you only want to know when something fails, set only errors: true. If you’re running long jobs and want periodic progress updates, enable progress: true, but expect more frequent messages.

Key Takeaways

  • Claude Code channels let you route agent activity and notifications to external platforms — Telegram is one of the simplest to set up.
  • The BotFather setup takes under five minutes and gives you an API token and a chat ID, which are the only two credentials you need.
  • Store credentials in environment variables rather than hardcoding them into your config file.
  • Test with simple tasks and use the Telegram getUpdates API endpoint to debug connection issues.
  • For more complex agent workflows — triggering tasks from external events, chaining outputs, connecting to other tools — MindStudio’s Agent Skills Plugin extends what Claude Code can do without adding significant complexity.

Start by creating your bot in BotFather, grab your credentials, and drop them into your Claude Code settings file. The whole process from zero to working notifications is about 10 minutes.

Presented by MindStudio

No spam. Unsubscribe anytime.