---

name: telegram description: Telegram Bot API 完整集成。包含 BotFather 设置、消息发送、Webhooks、内联键盘、群组、频道管理。提供 Node.js 和 Python 样板代码。 risk: critical source: community date_added: '2026-03-06' author: renat tags:

• messaging
• telegram
• bots
• webhooks tools:
• claude-code
• antigravity
• cursor
• gemini-cli
• codex-cli

---

Telegram Bot API - 专业集成

概述

Telegram Bot API 完整集成。包含 BotFather 设置、消息发送、Webhooks、内联键盘、群组、频道管理。提供 Node.js 和 Python 样板代码。

何时使用此技能

• 当用户提到 "telegram" 或相关话题时
• 当用户提到 "telegram 机器人" 或相关话题时
• 当用户提到 "telegram bot" 或相关话题时
• 当用户提到 "telegram api" 或相关话题时
• 当用户提到 "chatbot telegram" 或相关话题时
• 当用户提到 "telegram 消息" 或相关话题时

不适用场景

• 任务与 Telegram 无关
• 更简单、更专用的工具可以处理该请求
• 用户需要通用帮助而非领域专业知识

工作原理

使用官方 Bot API 在 Telegram 上实现专业机器人的技能。支持 Node.js/TypeScript 和 Python。

概述

Telegram Bot API 允许创建通过消息、命令、内联键盘、支付等方式与用户交互的机器人。机器人通过 @BotFather 创建，并通过唯一 token 进行身份验证。

基础 URL： https://api.telegram.org/bot<TOKEN>/METHOD_NAME HTTP 方法： GET 和 POST 参数格式： query string、application/x-www-form-urlencoded、application/json、multipart/form-data（上传） 文件限制： 下载 50MB，上传 20MB（通过 multipart），通过 URL 50MB

Webhook 支持的端口： 443、80、88、8443

前置条件：

• Telegram 账号
• 通过 @BotFather 创建的机器人（提供 token）
• Token 格式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

如果用户还没有创建机器人，引导其在 Telegram 中与 @BotFather 对话并发送 /newbot。

---

决策树

用户需要创建机器人吗？
├── 是 → 下方"BotFather 设置"章节
└── 否 → 使用什么语言？
    ├── Node.js/TypeScript
    └── Python
    → 想要做什么？
       ├── 发送消息 → "消息类型"章节
       ├── 接收消息 → "接收更新"章节
       ├── 交互式键盘 → "Keyboards"章节
       ├── 管理群组/频道 → references/chat-management.md
       ├── Webhook 设置 → references/webhook-setup.md
       ├── Inline 模式 → references/advanced-features.md
       ├── 支付功能 → references/advanced-features.md
       ├── AI 客服机器人 → "AI 自动化"章节
       └── 完整 API 参考 → references/api-reference.md

从零开始使用现成样板创建项目：

python scripts/setup_project.py --language nodejs --path ./meu-bot-telegram

## Ou

python scripts/setup_project.py --language python --path ./meu-bot-telegram

测试机器人 token 是否有效：

python scripts/test_bot.py --token "SEU_TOKEN"

发送测试消息：

python scripts/send_message.py --token "SEU_TOKEN" --chat-id "CHAT_ID" --text "Hello!"

---

BotFather 设置

1. 打开 Telegram 搜索 @BotFather
2. 发送 /newbot
3. 选择显示名称（例如："我的超棒机器人"）
4. 选择用户名（必须以 "bot" 结尾，例如：meu_incrivel_bot）
5. BotFather 返回 token——妥善保管
6. BotFather 常用命令：
   • /setdescription - 机器人描述
   • /setabouttext - "关于"文本
   • /setuserpic - 头像
   • /setcommands - 命令列表
   • /mybots - 管理现有机器人
   • /setinline - 启用 inline 模式
   • /setprivacy - 群组隐私模式

---

环境变量

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Node.js/TypeScript

// Instalar: npm install telegraf dotenv
// Para TypeScript: npm install -D typescript
import { Telegraf } from 'telegraf';
import dotenv from 'dotenv';
dotenv.config();

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);

bot.start((ctx) => {
  ctx.reply('Ola! Eu sou seu bot. Como posso ajudar?');
});

bot.on('text', (ctx) => {
  if (!ctx.message.text.startsWith('/')) {
    ctx.reply(`Voce disse: ${ctx.message.text}`);
  }
});

bot.launch();

Python

## Instalar: Pip Install Python-Telegram-Bot Python-Dotenv

import os
from dotenv import load_dotenv
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

load_dotenv()

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text('Ola! Eu sou seu bot. Como posso ajudar?')

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(update.message.text)