Claude Code Telegram Bot Deployment Guide: From Zero to Running > This article corresponds to the project claude-telegram-bot.zip, and each step is marked with the corresponding project file. > Expect to take 15–20 minutes. --- ## 0. What will you get? After the configuration is completed, you can send messages to your Bot on any Telegram client (mobile phone, desktop, web page). Claude Code runs behind the Bot, which can help you: - Collect fragmented information → Organize into structured daily reports - Generate formatted reports based on data - Remember notes, summarize information, and handle chores. All outputs are directly presented in the TG dialog box, without switching to other tools. > TG = Telegram, all "TG" below refer to the Telegram instant messaging platform. --- ## 1. Environment preparation ### 1.1 Install Claude Code If you haven't installed Claude Code yet, install it first: bash # macOS / Linux npm install -g @anthropic-ai/claude-code Verification: bash claude --version As long as you can see the version number. ### 1.2 Installing the Bun Telegram plug-in forces dependence on the Bun runtime, neither Node.js nor Deno. bash curl -fsSL https://bun.sh/install | bash After installation, open a new terminal window and verify: bash bun --version ### 1.3 An ordinary personal account is enough to have a Telegram account, no special permissions are required. > Corresponding file: CLAUDE.md → The "Technology Stack" and "Deployment Process" sections record these dependencies. --- ## 2. Create Telegram Bot ### 2.1 Open BotFather and search for @BotFather in Telegram, or open the link directly: https://t.me/BotFather ### 2.2 Create a new Bot and send it to BotFather: /newbot It will ask you two questions in turn: Question 1 — Name (display name) This is the name displayed at the top of the chat. It can be in Chinese and has spaces. It is recommended to choose a name that you can recognize at a glance, such as: Report Assistant Question 2 - Username (user name) This is the unique identifier of the Bot. It must end with bot and can only use English, numbers and underscores. For example: my_report_helper_bot ### 2.3 Save Token The message BotFather replies to will have a line long like this: 123456789:AAHfiqksKZ8WxYz1a2b3c4d5e6f7g8h9 This is the Token, copy it completely, including the beginning number and the colon in the middle. > ⚠️ Token is equivalent to password. Anyone who gets this Token can fully control your Bot. Do not post to the group or submit to Git. ### 2.4 Write down the Bot’s username and fill in the username you set into the configuration that will be used later. The format is @my_report_helper_bot. > Corresponding file: agents/report-bot/config/.env.example — Token is written in the format of this file. --- ## 3. Unzip the project & fill in the configuration ### 3.1 Unzip bash unzip claude-telegram-bot.zip cd claude-telegram-bot ### 3.2 Take a look at the directory structure. ├── CLAUDE.md # Claude Code global command ├── agents/ │ └── report-bot/ │ ├── IDENTITY.md # Bot’s identity and behavior definition │ ├── USER.md # ← The file you want to fill in │ ├── config/ │ │ ├── .env.example │ │ └── access.json.example │ └── workspace/ │ ├── daily.md │ └── daily.md │ └── scratch/ └── scripts/ ├── setup.sh └── start.sh ``` ### 3.3 Fill in USER.md (important) Open `agents/report-bot/USER.md` and replace the placeholders with your real information: ```bash vim agents/report-bot/USER.md # Or use your favorite editor Required fields: | Field| Where| How to fill| |-------|--------|--------| | Title| "Basic information" form| You want Bot How to call you | | TG User ID | "Basic information" form | Numeric ID, the next section will teach you how to get it | etc.), fill it in here, and the Bot will not misunderstand - "Communication Style Preference" - "Direct, Active, Compact" is configured by default. If you are not satisfied, you can change it### 3.4 Get your Telegram User ID. Search @userinfobot in Telegram and send it any message. It will immediately reply with your numeric ID, similar to: Id: 412587349 ``` Write down this number and fill it in `USER.md` "TG User ID" field. ### 3.5 Check IDENTITY.md (optional) `agents/report-bot/IDENTITY.md` defines the Bot's role, behavior specifications and output format. The default configuration is already complete, but you can fine-tune it as needed: - Daily template format ("Daily Organizing Specifications" section) - Prohibited matters (things you don't want Bot to do) - Sample dialogue (let Bot understand the interaction you expect) > **Corresponding files**: `agents/report-bot/IDENTITY.md` + `agents/report-bot/USER.md` --- ## 4. Install the Telegram plug-in ### 4.1 Start Claude Code ```bash claude ``` Enter the interactive session of Claude Code. ### 4.2 To install the plug-in, enter in the session: ``` /plugin install telegram@claude-plugins-official ``` and wait for it to finish installing. Then enter: ``` /reload-plugins ``` ### 4.3 Verify the installation Try entering `/telegram:` and press the Tab key. If you can complete commands such as `configure`, it means the installation is complete. If it cannot be completed, exit the session (type `exit`), rerun `claude`, and try again. --- ## 5. Configure Token ### 5.1 Configure in the Claude Code session and fill in the Token obtained in step 2: ``` /telegram:configure 123456789:AAHfiqksKZ8WxYz1a2b3c4d5e6f7g8h9 ``` This command will Write `~/.claude/channels/telegram/.env`. ### 5.2 Or write the file manually if you prefer to do it manually: ```bash mkdir -p ~/.claude/channels/telegram echo "TELEGRAM_BOT_TOKEN=123456789:AAHfiqksKZ8WxYz1a2b3c4d5e6f7g8h9" > ~/.claude/channels/telegram/.env chmod 600 ~/.claude/channels/telegram/.env ``` `chmod 600` Make sure only you can read this file. > **Corresponding file**: `agents/report-bot/config/.env.example` is the template of this file. --- ## 6. Configure access control. Copy the access control template in the project to the configuration directory of the Telegram plug-in: ```bash cp agents/report-bot/config/access.json.example ~/.claude/channels/telegram/access.json ``` Then edit and replace `YOUR_TELEGRAM_USER_ID` with the numeric ID you got in step 3.4: ```bash vim ~/.claude/channels/telegram/access.json ``` Change this line: ```json "allowFrom": ["412587349"], ``` > **Corresponding file**: `agents/report-bot/config/access.json.example` > > There is also `mention in itThe Patterns` field is equipped with "daily report", "report", "organizing", and "note" as group trigger words. If you only use private messages, this will not affect you. --- ## 7. Starting this step with the Channel parameter is critical. **Without the `--channels` parameter, the plug-in will not connect to Telegram. ** Exit the current Claude Code session first: ``` exit ``` Then restart with the following command: ```bash claude --channels plugin:telegram@claude-plugins-official ``` Or directly use the script in the project: ```bash ./scripts/start.sh ``` After starting, you should be able to see Claude Code enter the session normally without reporting an error. > **Corresponding file**: `scripts/start.sh` encapsulates this command with pre-checking. --- ## 8. Pairing ### 8.1 To initiate pairing, open Telegram, find the Bot you created (search for `@my_report_helper_bot` or the username you set), send it a message, anything will do: Hello### 8.2 After receiving the pairing code, the Bot will reply with a 6-digit pairing code, similar to: ```` Your pairing code is: a4f91c ```` ### 8.3 Confirm in Claude Code to return to the Claude Code session, enter: /telegram:access pair a4f91c After successful pairing, the next message you send in Telegram will directly reach the Claude Code assistant. ### 8.4 Test it by sending the Bot on Telegram: I had a code review and product review meeting todayThe Bot should reply with the compiled content. If the Bot uses 👀 react to your message and then replies with a structured daily report, congratulations, the configuration is complete. --- ## 9. Lock secure pairing just to get your User ID. Once completed, you must switch to allowlist mode, otherwise anyone who finds your Bot username will be able to obtain the pairing code. In the Claude Code session, enter: /telegram:access policy allowlist or directly edit `~/.claude/channels/telegram/access.json` and confirm:json "dmPolicy": "allowlist" From now on, only users in the `allowFrom` list can interact with the Bot. --- ## 10. Daily use ### You need to start Claude Code before each use:bash cd claude-telegram-bot ./scripts/start.sh ### Daily report process 1. Send fragmented information to the Bot at any time during the day: "I had a XX meeting in the morning", "Fixed 3 bugs", "Written half of the PRD" 2. Send a "organized daily report" or "What have you done today" before get off work? 3. Bot outputs a structured daily report 4. If you need to modify it, just say "Change XX to YY", and Bot uses `edit_message` to modify it in place### Report process 1. Send data to Bot (text, screenshot, or file) 2. Say "organize it according to XX dimensions" or "make a report" 3. Bot outputs formatted report### Memo - "Remember: I will have a meeting with Mr. Zhang at 10 o'clock tomorrow" - "Remind me to submit XX document next week" (Bot will record it but it shows that it does not have the ability to remind regularly) > **Corresponding file**: `agents/report-bot/IDENTITY.md` → The "Your Code of Conduct" section defines these workflows. > `agents/report-bot/workspace/templates/` contains output templates for daily and weekly reports. --- ## 11. Advanced configuration ### 11.1 Add more users /telegram:access allow 628194073 Or edit `access.json`:json "allowFrom": ["412587349", "628194073"] ### 11.2 Enable groups /telegram:access group add -1001654782309 Bots in the group will only respond to @mentions by default. If you want it to respond to all messages: /telegram:access group add -1001654782309 --no-mention Note: `--no-mention` also needs to disable privacy mode in BotFather: send `/setprivacy` to `@BotFather` → select your Bot → select Disable. ### 11.3 Customize the confirmation emoticon when receiving a message. The default is 👀, which can be changed: /telegram:access set ackReaction ❤ ` The available emoticons are Telegram’s fixed whitelist: 👍 👎 ❤ 🔥 👏 🤔 🤯 😢 🎉 👀 etc. ### 11.4 Custom trigger words (for groups) /telegram:access set mentionPatterns '["^daily report", "^report", "^hey bot"]' ### 11.5 Running multiple Bots Each Bot requires a different `TELEGRAM_STATE_DIR`: ``bash # Bot 1: Report assistant TELEGRAM_STATE_DIR=~/.claude/channels/telegram-report claude --channels plugin:telegram@claude-plugins-official # Bot 2: Other uses TELEGRAM_STATE_DIR=~/.claude/channels/telegram-other claude --channels plugin:telegram@claude-plugins-official `` Create a new `agents/other-bot/` in the project directory, write its own `IDENTITY.md` and `USER.md`. --- ## 12. Troubleshooting ### Bot does not respond at all 1. Confirm that Claude Code is started with `--channels plugin:telegram@claude-plugins-official` 2. Confirm that the Token is correct: `cat ~/.claude/channels/telegram/.env` 3. Confirm that the Bot is not occupied by other programs (one Token can only be used by one process at the same time) ### The pairing code has not been received 1. Confirm that `dmPolicy` is `pairing` (not `allowlist`), you need to use `pairing` mode during pairing 2. Confirm that you DM Bot directly, not in the group ### The Bot responds but the output is strange. Check whether `IDENTITY.md` is read correctly. Ask in Claude Code:What is your identity? What are you responsible for? If the answer does not match the description of `IDENTITY.md`, it may be that Claude Code has not read the project file. Make sure you start it in the project directory. ### Blurred pictures Telegram will automatically compress pictures. If you need the original image, press and hold → select "Send as file" when sending. --- ## File Cheat Sheet | File | Function | What you need to do | |------|------|-------------| | `CLAUDE.md` | Claude Code global directive | No need to change | | `agents/report-bot/IDENTITY.md` | Bot Identity and Behavior Specifications | Can be fine-tuned | `agents/report-bot/config/.env.example` | Token template | Reference format | | `agents/report-bot/config/access.json.example` | Access control template | Copy to system directory and change ID | | `agents/report-bot/workspace/templates/` | Daily/weekly report template | Customizable | | `scripts/setup.sh` | Installation wizard | Run once | | `scripts/start.sh` | Quick start | Use for each startup | --- ## Complete command quick checkbash # ========== Installation phase (only do it once) ========== curl -fsSL https://bun.sh/install | bash # Install Bun claude # Start Claude Code /plugin install telegram@claude-plugins-official # Install plug-in/telegram:configure # With Token exit # Exit # ========== Daily startup ========== cd claude-telegram-bot ./scripts/start.sh # Start # ========== Pairing & Security ========== /telegram:access pair # pair/telegram:access policy allowlist # Lock # ========== Management ========== /telegram:access # View status /telegram:access allow #Add people/telegram:access remove # Delete people/telegram:access group add # Add group/telegram:access set ackReaction 👀 # Change expression```

files.zip

download