Telegram bot — local setup guide — Guides

Telegram bot

Telegram bot — local setup guide

Set up a Claude Code Telegram bot running on your own computer with auto-start.

What this sets up

A Python Telegram bot running on your own computer that:

Forwards messages to Claude Code CLI and streams responses back in real time
Supports text, images, voice messages (transcribed via OpenAI Whisper), audio files, and documents
Persists conversation sessions across bot restarts
Reply context — replying to a previous message includes the quoted text so Claude understands what you're referring to
MCP integrations — optionally connects to Notion, Figma, and Slack via Claude's MCP tools
Only responds to you — everyone else is silently ignored
Starts automatically when your computer starts (no manual terminal step each day)

Important caveat: The bot only works while your computer is on and awake. It won't respond if your computer is off, sleeping, or the lid is closed. Close the terminal window after setup — the bot keeps running in the background — but your computer needs to stay on.

Step 0: Collect everything before touching the terminal

Ask the user these five questions, one at a time. Do not proceed to installation until you have all the answers.

Question 1: What operating system are you on?

Mac
Windows
Linux

Question 2: Do you have a Claude Pro, Team, or Enterprise subscription?

Claude Code requires a paid plan. Free accounts won't work. If they don't have one: go to claude.ai/upgrade first. Do not proceed with installation.

About credits: Claude Pro includes a generous daily usage quota. Under heavy bot use, you may occasionally hit the limit — the bot will tell you when this happens. It resets automatically. This is normal, not a bug.

Question 3: Get your Telegram bot token

Open Telegram and search for @BotFather
Send the message: /newbot
Choose a display name (e.g. "My Claude Bot")
Choose a username ending in bot (e.g. myclaudehelper_bot)
BotFather will reply with a token that looks like: 1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ

Keep this token secret — anyone who has it can control your bot.

Ask the user to paste their token here. Save it — you'll fill it into the bot script automatically.

Question 4: Get your Telegram user ID

Open Telegram and search for @userinfobot
Send any message to it
It will reply with a number like 123456789

This is how the bot knows to only respond to you and ignore everyone else.

Ask the user to paste their user ID here. Save it.

Question 5: Do you want voice message support? (Optional)

Voice transcription uses OpenAI's Whisper API and requires an OpenAI account with API credits. This is completely optional — the bot works fine without it.

If yes: go to platform.openai.com, create an API key, and paste it here. Save it.
If no: skip this. The bot will tell you voice isn't available if you send one, but everything else will work normally.

Mac Setup

Check what's already installed

Before installing anything:

bash

node --version

If it prints v18.x.x or higher, skip to "Check Python".

bash

python3 --version

If it prints 3.10.x or higher, skip to "Check Claude Code".

bash

claude --version

If it prints a version number, skip to "Install Python packages".

Install Homebrew (if needed)

bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Your Mac password won't show as you type — this is normal. Just type it and press Enter.
If it mentions installing Xcode Command Line Tools, that's fine. Let it run. This can take a few minutes.

The PATH step — do not skip this

When Homebrew finishes, look at the last few lines it printed. If you see a section titled "Next steps:" or "Run these commands:", it will show you two lines that look like this (yours may be slightly different):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Copy the exact lines shown on your screen (not the ones above) and paste them into the terminal, then press Enter. Without this step, Homebrew won't work.

If no "Next steps" section appeared, you don't need to do anything.

Verify:

bash

brew --version

Should print Homebrew 4.x.x. If it says command not found, the PATH step was missed — close the terminal, open a new one, and run the two lines again.

Install Node.js and Python

bash

brew install node python

Verify:

bash

node --version
python3 --version

Node should be v18 or higher. Python should be 3.10 or higher.

Install Claude Code

bash

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zprofile
source ~/.zprofile
npm install -g @anthropic-ai/claude-code

Verify:

bash

claude --version

Log into Claude Code and test it

bash

claude

Inside the session, type:

/login

A browser window opens. Log in with your Claude account.

If the browser doesn't open, copy the URL printed in the terminal and paste it into your browser manually.

Once logged in, test that it actually works by typing a message like say hello. Claude should respond. If it does, type:

/exit

If it doesn't respond or shows an error, stop here — debug the Claude Code login before proceeding.

Set up a virtual environment and install Python packages

A virtual environment keeps the bot's packages isolated and avoids system conflicts.

bash

python3 -m venv ~/claude-telegram-bot/venv
source ~/claude-telegram-bot/venv/bin/activate
pip install "python-telegram-bot==20.*" openai

Create the bot script

Claude will write this file for you with your actual token, user ID, and OpenAI key already filled in. Run this command to write the file directly:

bash

cat > ~/claude-telegram-bot/telegram_bot.py << 'ENDOFSCRIPT'
PASTE THE COMPLETE SCRIPT HERE
ENDOFSCRIPT

(Claude: replace PASTE THE COMPLETE SCRIPT HERE with the full bot script from the "Bot Script" section at the bottom of this guide, with the user's actual credentials filled in.)

Reading this yourself? The complete bot script is in the "Bot Script" section near the bottom of this file. Copy it, fill in your credentials at the top, and save it as telegram_bot.py.

Verify the file exists:

bash

ls ~/claude-telegram-bot/telegram_bot.py

Test the bot manually first

Before setting up auto-start, confirm the bot works:

bash

source ~/claude-telegram-bot/venv/bin/activate
python3 ~/claude-telegram-bot/telegram_bot.py

The terminal should show "Bot started. Polling for messages..."

Test it now: Open Telegram and send your bot the message hello. You should see "Thinking..." appear within a few seconds, followed by a response from Claude. If that happens, the bot works. Press Ctrl+C to stop it, then set up auto-start below.

Create a launch agent that starts the bot automatically every time you log into your Mac:

bash

cat > ~/Library/LaunchAgents/com.claude.telegrambot.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claude.telegrambot</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOURUSERNAME/claude-telegram-bot/venv/bin/python3</string>
        <string>/Users/YOURUSERNAME/claude-telegram-bot/telegram_bot.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOURUSERNAME/claude-telegram-bot/bot.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOURUSERNAME/claude-telegram-bot/bot.log</string>
</dict>
</plist>
EOF

(Claude: replace YOURUSERNAME with the user's actual Mac username. To find it, run whoami in the terminal and use that output.)

Load it:

bash

launchctl load ~/Library/LaunchAgents/com.claude.telegrambot.plist

Verify it's running:

bash

launchctl list | grep claude

Should show a line with com.claude.telegrambot.

Test it by sending hello to the bot on Telegram. It should respond.

To check logs if something is wrong:

bash

tail -f ~/claude-telegram-bot/bot.log

To stop the bot:

bash

launchctl unload ~/Library/LaunchAgents/com.claude.telegrambot.plist

To start it again:

bash

launchctl load ~/Library/LaunchAgents/com.claude.telegrambot.plist

The bot will now start automatically every time you log in. No terminal needed day to day.

Windows Setup

Open PowerShell

Press the Windows key
Type PowerShell
Click Windows PowerShell (not "ISE", not "x86")

Check what's already installed

powershell

node --version

If it prints v18.x.x or higher, skip to "Check Python".

powershell

python --version

If it prints 3.10.x or higher, skip to "Check Claude Code".

powershell

claude --version

If it prints a version number, skip to "Install Python packages".

Install Node.js (if needed)

Go to https://nodejs.org
Click the LTS button
Run the installer, click Next through everything, keep all defaults
Click Install, then Finish

Close PowerShell and open a new one. Then verify:

powershell

node --version

Install Python (if needed)

Go to https://python.org
Click Downloads, then the big yellow button
Run the installer
Check the box "Add python.exe to PATH" at the bottom — this is critical
Click Install Now

Close PowerShell and open a new one. Then verify:

powershell

python --version

Install Claude Code (if needed)

powershell

npm install -g @anthropic-ai/claude-code

If you get a permission error, close PowerShell, right-click Windows PowerShell, select Run as administrator, then try again.

Verify:

powershell

claude --version

Log into Claude Code and test it

powershell

claude

Type /login. Log in via the browser that opens. If the browser doesn't open, copy the URL from the terminal and paste it into your browser manually.

Once logged in, test it by typing a message like say hello. If Claude responds, type /exit.

Set up a virtual environment and install Python packages

powershell

New-Item -ItemType Directory -Force -Path "$HOME\claude-telegram-bot"
cd "$HOME\claude-telegram-bot"
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install "python-telegram-bot==20.*" openai

If PowerShell says "running scripts is disabled", run this first:

powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then try the activate command again.

Create the bot script

Claude will generate this file with your credentials already filled in. In your activated virtual environment:

powershell

cd "$HOME\claude-telegram-bot"

Then Claude will write the file content. Copy and paste the script Claude provides and save it as telegram_bot.py in that folder.

The easiest way: Claude generates the script, you copy it, open Notepad, paste it, then File → Save As → navigate to C:\Users\YOURUSERNAME\claude-telegram-bot\, set "Save as type" to "All Files", and name it telegram_bot.py.

Reading this yourself? The complete bot script is in the "Bot Script" section near the bottom of this file.

Test the bot manually first

powershell

cd "$HOME\claude-telegram-bot"
.\venv\Scripts\Activate.ps1
python telegram_bot.py

Should show "Bot started. Polling for messages..."

Test it: Send hello to your bot on Telegram. You should see "Thinking..." then a response from Claude. If it works, press Ctrl+C.

Run this in PowerShell to create a scheduled task:

powershell

$action = New-ScheduledTaskAction `
    -Execute "$HOME\claude-telegram-bot\venv\Scripts\python.exe" `
    -Argument "$HOME\claude-telegram-bot\telegram_bot.py" `
    -WorkingDirectory "$HOME\claude-telegram-bot"

$trigger = New-ScheduledTaskTrigger -AtLogOn

$settings = New-ScheduledTaskSettingsSet `
    -ExecutionTimeLimit 0 `
    -RestartCount 3 `
    -RestartInterval (New-TimeSpan -Minutes 1)

Register-ScheduledTask `
    -TaskName "ClaudeTelegramBot" `
    -Action $action `
    -Trigger $trigger `
    -Settings $settings `
    -RunLevel Highest `
    -Force

Start it now without restarting:

powershell

Start-ScheduledTask -TaskName "ClaudeTelegramBot"

Verify it's running:

powershell

Get-ScheduledTask -TaskName "ClaudeTelegramBot"

To stop the bot:

powershell

Stop-ScheduledTask -TaskName "ClaudeTelegramBot"

To start it again:

powershell

Start-ScheduledTask -TaskName "ClaudeTelegramBot"

To remove it entirely:

powershell

Unregister-ScheduledTask -TaskName "ClaudeTelegramBot" -Confirm:$false

The bot will now start automatically at every login.

Linux Setup

Open the terminal

Ubuntu/Debian: press Ctrl + Alt + T
Or search "Terminal" in the application menu

Check what's already installed

bash

node --version
python3 --version
claude --version

Skip any install step where the version check prints a valid version.

Install Node.js (if needed)

bash

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs

For Fedora/Arch/other distros, ask Claude which package manager commands to use.

Install Python (if needed)

bash

sudo apt install -y python3 python3-pip python3-venv

Install Claude Code (if needed)

bash

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Log into Claude Code and test it

bash

claude

Type /login. If the browser doesn't open, copy the URL from the terminal.

Test with a message like say hello. If it works, type /exit.

Set up a virtual environment and install Python packages

bash

mkdir -p ~/claude-telegram-bot
python3 -m venv ~/claude-telegram-bot/venv
source ~/claude-telegram-bot/venv/bin/activate
pip install "python-telegram-bot==20.*" openai

Create the bot script

Claude will generate this with your credentials filled in. Write it directly:

bash

nano ~/claude-telegram-bot/telegram_bot.py

nano is a terminal text editor — it looks different from a normal app. Just paste the script, then press Ctrl+O to save, Enter to confirm, Ctrl+X to exit.

Reading this yourself? The complete bot script is in the "Bot Script" section near the bottom of this file.

Test the bot manually first

bash

source ~/claude-telegram-bot/venv/bin/activate
python3 ~/claude-telegram-bot/telegram_bot.py

Test it: Send hello to your bot on Telegram. You should see "Thinking..." then a response. If it works, press Ctrl+C.

Set up auto-start on Linux (systemd user service)

Create the service file:

bash

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/claude-telegram-bot.service << EOF
[Unit]
Description=Claude Telegram Bot
After=network.target

[Service]
Type=simple
ExecStart=%h/claude-telegram-bot/venv/bin/python3 %h/claude-telegram-bot/telegram_bot.py
WorkingDirectory=%h/claude-telegram-bot
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
EOF

Enable and start it:

bash

systemctl --user daemon-reload
systemctl --user enable claude-telegram-bot
systemctl --user start claude-telegram-bot

Allow it to run when you're not logged in (optional but recommended):

bash

loginctl enable-linger $USER

Check status:

bash

systemctl --user status claude-telegram-bot

Check logs:

bash

journalctl --user -u claude-telegram-bot -f

Stop the bot:

bash

systemctl --user stop claude-telegram-bot

Start it again:

bash

systemctl --user start claude-telegram-bot

Optional: Adding MCP integrations

To let Claude access Notion, Figma, or Slack from within the bot, add the MCP tool patterns to the ALLOWED_TOOLS list in the script:

python

ALLOWED_TOOLS = ",".join([
    "Edit", "Write", "Read", "Bash", "Glob", "Grep",
    "Agent", "WebFetch", "WebSearch",
    "mcp__claude_ai_Notion*",   # Read/write Notion pages
    "mcp__claude_ai_Figma*",    # Analyze Figma designs
    "mcp__claude_ai_Slack*",    # Read/send Slack messages
])

MCP servers are configured in your Claude Code settings. To manage them, run claude in a terminal and type /mcp to see available integrations. After changing the script, restart the bot using the platform-specific commands above.

Day-to-day use

Once auto-start is set up, you don't need to do anything — the bot starts when your computer starts and runs in the background.

About credits: Claude Pro includes a generous daily usage quota. Under heavy use, you may hit the limit and see a "credits have run out" message. This resets automatically — wait a few hours or until the next day. This is normal, not a bug.

Commands in the bot:

/start — confirm the bot is alive and reset the current session
/new — start a fresh conversation with Claude

The bot works while your computer is on and awake. It won't respond while the computer is off, sleeping, or before you've logged in.

Troubleshooting

Problem	Fix
Bot doesn't respond at all	Check the bot is running: Mac → `launchctl list
"Credits have run out" message	Normal — Claude Pro has a daily quota. Wait a few hours and try again
"command not found" after installing	Close terminal, open a new one, try again
"Permission denied"	Mac/Linux: use the npm-global prefix approach. Windows: run PowerShell as Administrator
"Another instance is already running"	Stop the other instance or delete the lock file: Mac/Linux → `rm ~/.claude-telegram.lock`, Windows → `del "$HOME\.claude-telegram.lock"`
Voice not working	Make sure your OpenAI API key is set in the script and has credits at platform.openai.com
"No module named 'telegram'"	Activate the venv first: Mac/Linux → `source ~/claude-telegram-bot/venv/bin/activate`, Windows → `.\venv\Scripts\Activate.ps1`, then run `pip install "python-telegram-bot==20.*"`
Browser doesn't open for Claude login	Copy the URL printed in the terminal and paste it into your browser
Bot logs for debugging	Mac → `tail -f ~/claude-telegram-bot/bot.log`, Linux → `journalctl --user -u claude-telegram-bot -f`, Windows → check the Task Scheduler history
Claude login says "no active subscription"	You need Claude Pro ($20/month), Team, or Enterprise at claude.ai/upgrade

What's next?

Your bot works. It answers questions, reads files, writes code, and handles voice messages. But right now it forgets everything between sessions and doesn't connect to any of your other tools.

A follow-up guide (coming soon) covers how to make it truly useful:

CLAUDE.md — teach Claude who you are, how you work, and what to remember
Persistent memory — Claude remembers context across conversations
MCP integrations — connect Notion, Slack, Google Calendar, and more
Custom commands — add your own workflows (content drafting, daily briefs, etc.)
Backups — so you don't lose everything if the server dies