Telegram Toolkit Free

Free Telegram Bot workflow toolkit focusing on command routing, update handling, HTTP templates, and security for AI Agent integration.

TG机器人工具（免费版）

本工具为独立开发者、运维与AI Agent提供Telegram Bot工作流的设计与实现能力。免费版聚焦核心场景：命令路由设计、更新处理、HTTP请求模板、安全配置，足以覆盖命令式Telegram机器人的绝大多数日常需求。

概述

Telegram Bot API是构建对话式机器人与自动化通知通道的主流方案。一个专业的Telegram机器人应当具备清晰的命令路由、可靠的更新处理、规范的请求构造与完善的安全配置。本工具将这些经过生产验证的实践模式整合为一套设计指南，帮助用户在不依赖重型SDK的前提下，通过原生HTTPS调用构建专业、可靠的机器人。

本工具以命令优先（command-first）的交互范式为核心，强调通过/start、/help、/settings等结构化命令提供确定性的用户体验，而非依赖自然语言理解的模糊交互。

核心能力

能力分类	说明
命令路由	/start、/help、/settings、/status等结构化命令分发
更新处理	webhook与长轮询两种策略的选择与配置
请求模板	sendMessage、editMessage、answerCallback等HTTP payload
更新归一化	将不同更新类型归一化为统一处理结构
安全配置	Token保护、Webhook密钥、速率限制、payload校验
错误处理	429限流退避、超时重试、错误码恢复
技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置。

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Agent、Telegram、Bot、工作流设计工具免、覆盖命令路由、安全配置核心能力、面向独立开发者与、聚焦命令优先的机、器人交互设计、或长轮询、请求模板与安全配、提供生产可用的命、令路由规范与更新、归一化处理模式、帮助用户快速构建、可靠的、机器人、Use、when、模型调用、智能对话、LLM、应用时使用、不适用于需要、确定性的关键决策等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：命令式服务机器人（开发者视角）

构建以/start、/help、/status为核心命令的服务机器人，提供确定性的指令响应体验。

场景二：AI Agent通知通道（Agent视角）

将Telegram Bot作为AI Agent的输出通道，在关键节点（任务完成、异常告警）主动推送消息给用户。

场景三：自动化工作流触发（运维视角）

通过Telegram命令触发自动化工作流，如/deploy触发部署、/backup触发备份，实现移动化运维。

场景四：指令式数据查询（产品视角）

通过/query <参数>命令查询业务数据并返回格式化结果，作为轻量级的数据访问入口。

快速开始

第一步：配置机器人Token

bash

# 通过 @BotFather 创建机器人并获取Token
# Token格式：123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
# ...
# 通过环境变量注入（禁止硬编码）
export TG_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"

第二步：选择更新处理策略

bash

# 策略一：长轮询（开发环境推荐，无需公网IP）
# 主动调用 getUpdates 拉取更新
# ...
# 策略二：Webhook（生产环境推荐，实时性好）
curl -X POST "https://api.telegram.org/bot${TG_BOT_TOKEN}/setWebhook" \
  -d "url=https://your-domain.com/webhook" \
  -d "secret_token=your_secret_token"

第三步：实现命令路由

python

import os
import requests
# ...
TOKEN = os.environ["TG_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
# ...
def handle_update(update):
    message = update.get("message", {})
    text = message.get("text", "")
    chat_id = message.get("chat", {}).get("id")
# ...
    if text == "/start":
        reply = "欢迎使用！输入 /help 查看可用命令。"
    elif text == "/help":
        reply = "可用命令：\n/start - 开始\n/help - 帮助\n/status - 状态"
    elif text == "/status":
        reply = "服务运行正常"
    else:
        reply = "未知命令，输入 /help 查看可用命令"
# ...
    requests.post(f"{API}/sendMessage", json={
        "chat_id": chat_id,
        "text": reply
    })

完整上手时间约60秒。

示例

Webhook安全配置

bash

# 设置Webhook时携带secret_token
curl -X POST "https://api.telegram.org/bot${TG_BOT_TOKEN}/setWebhook" \
  -d "url=https://your-domain.com/webhook" \
  -d "secret_token=$(openssl rand -hex 32)" \
  -d "allowed_updates=[\"message\",\"callback_query\"]"
# ...
# 服务端校验 secret_token 头
# HTTP header: X-Telegram-Bot-Api-Secret-Token

命令注册（BotFather）

bash

# 通过 setMyCommands 注册命令列表，显示在输入框快捷菜单
curl -X POST "https://api.telegram.org/bot${TG_BOT_TOKEN}/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"command": "start", "description": "开始使用"},
      {"command": "help", "description": "查看帮助"},
      {"command": "settings", "description": "个人设置"},
      {"command": "status", "description": "服务状态"}
    ]
  }'

已知限制

python

import time
# ...
def send_with_retry(chat_id, text, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(f"{API}/sendMessage", json={
            "chat_id": chat_id, "text": text
        })
        if resp.status_code == 200:
            return
        elif resp.status_code == 429:
            # 限流：按retry_after等待
            retry_after = resp.json().get("parameters", {}).get("retry_after", 5)
            time.sleep(retry_after)
        else:
            time.sleep(2 ** attempt)  # 指数退避

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

最佳实践

1. 命令优先，自然语言辅助

专业机器人应以结构化命令（/start、/help）为核心交互方式，提供确定性体验。自然语言理解可作为辅助，但不应作为唯一入口。

2. 始终校验更新payload

python

def handle_update(update):
    if not update.get("message") and not update.get("callback_query"):
        return  # 忽略非预期更新类型
    # 校验chat_id是否在白名单（如需限制访问）

3. 生产环境用Webhook

长轮询适合开发调试，生产环境推荐Webhook：实时性更好、资源占用更低。务必配置secret_token防止伪造请求。

4. 处理429限流

Telegram对消息发送有速率限制（约每秒30条、每分钟20条到同一聊天）。遇到429时按retry_after等待，避免消息洪流。

5. Token绝不落盘明文

python

# 正确：从环境变量读取
TOKEN = os.environ["TG_BOT_TOKEN"]
# ...
# 错误：硬编码在代码中
TOKEN = "123456789:ABCdef..."  # 禁止

常见问题

Q1：Webhook收不到更新怎么办？

A：(1) 确认URL为HTTPS且证书有效；(2) 检查setWebhook返回是否成功；(3) 确认服务器公网可达且端口为443/80/88/8443；(4) 用getWebhookInfo查看最近错误信息。

Q2：长轮询和Webhook如何选择？

A：开发环境用长轮询（无需公网IP，调试方便）；生产环境用Webhook（实时性好、资源占用低）。两者不可同时启用。

Q3：如何限制机器人只服务特定用户？

A：在handle_update中校验chat_id是否在白名单，非白名单用户忽略或返回拒绝提示。也可用chat_member更新类型处理成员变动。

Q4：429限流频繁出现怎么办？

A：(1) 避免短时间内向同一聊天发送大量消息；(2) 批量通知用sendMessage的disable_notification参数；(3) 长文本拆分发送时加适当间隔；(4) 实现429退避机制。

Q5：如何处理回调按钮（Inline Keyboard）？

A：用户点击按钮会产生callback_query更新，通过answerCallbackQuery响应并editMessageText更新原消息。务必在30秒内应答callback，否则按钮会一直显示加载状态。

Q6：机器人在群里只响应命令不响应闲聊？

A：在群中默认机器人不接收所有消息。需通过setWebhook的allowed_updates或getUpdates的offset配置。建议只处理以/开头的命令消息，忽略普通聊天。

免费版限制

本免费体验版限制以下高级功能：

• 不支持复杂对话状态机与会话管理
• 不支持富媒体消息模板库（图片、视频、文件）
• 不支持多机器人统一管理面板
• 不支持消息队列削峰与批量发送
• 不支持Webhook健康监控与自动告警

解锁全部功能请使用专业版：telegram-toolkit-pro

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 网络: 需能访问 api.telegram.org
• Python: 3.8+（用于示例代码）

依赖详情

依赖项	类型	是否必需	获取方式
requests	Python包	必需	pip install requests
Python	运行时	必需	python.org 官方下载
HTTPS证书	证书	可选	Webhook模式需要有效SSL证书

API Key 配置

• TG_BOT_TOKEN: 通过 @BotFather 获取，存入环境变量，禁止硬编码
• Webhook secret_token: 设置Webhook时生成，服务端校验请求头

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

json

{
  "success": true,
  "data": {
    "result": "TG机器人工具(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "telegramkit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}