Telegram Bot API 教程：从零开始搭建你的第一个机器人
一份实用的 Telegram Bot API 教程：获取 BotFather 令牌，调用 sendMessage 和 getUpdates，设置 Webhook，处理速率限制，并发布你的第一个机器人。
最快的 Telegram Bot API 教程只需三步：从 BotFather 获取令牌，调用 getUpdates 读取消息，然后调用 sendMessage 进行回复。机器人开发中的其他一切都建立在这个循环之上。本指南将带你走完整个过程，从你的第一个 cURL 请求，到拥有 Webhook 和库的运行中的机器人。
Bot API 是一个 HTTP 接口，这意味着你可以在编写任何应用程序代码之前，先用 curl 进行测试。这使得它成为最容易学习的 API 之一。如果你是一名希望今天就能拥有一个可用机器人的开发者，或者正在权衡代码开发与像 TeleClaw 这样的无代码平台的构建者，那么你来对地方了。
学完本教程，你将了解 API 如何进行身份验证、如何接收和发送消息、长轮询和 Webhook 之间的区别，以及大多数新手机器人都会遇到的速率限制问题。
核心要点
- 机器人本质上就是一个 HTTP 客户端。 每个方法都是对
https://api.telegram.org/bot<TOKEN>/METHOD_NAME的请求，所以cURL足以让你开始。 - 三个核心方法让你快速上手：
getMe用于验证令牌，getUpdates用于读取消息，sendMessage用于回复。 - 长轮询和 Webhook 互斥。 本地测试时使用轮询，生产环境切换到 Webhook。
- API 是免费的， 但 Telegram 对批量发送的限制大约是每秒向不同用户发送 30 条消息，每个聊天每秒一条。
- 当你的机器人不再是简单的脚本时，使用库可以节省大量时间。 推荐使用 python-telegram-bot、aiogram 或 Telegraf。
什么是 Telegram Bot API？
Telegram Bot API 是一个基于 HTTP 的接口，用于通过机器人将你的代码连接到 Telegram。根据 Telegram 的开发者介绍，机器人是一种特殊的账户，不需要手机号码，并作为运行在你服务器上的代码的接口。
你发出的每个请求都使用机器人令牌而不是用户账户进行身份验证。令牌用于识别机器人，因此你需要像对待密码一样对待它，绝不能将其提交到公共仓库。Telegram 的文档明确指出：将你的令牌保存在安全的地方，不要分享。
API 本身是免费的。自推出以来，Telegram 一直免费提供 Bot API，没有按消息收费，也没有创建机器人数量的上限。这就是为什么有如此多的社区工具、支持助手和自动化工具都运行在它之上。如果你是该平台的新手，我们的如何创建 Telegram 机器人指南更详细地介绍了账户设置方面的内容。
第一步：从 BotFather 获取机器人令牌
打开 Telegram 并搜索 @BotFather，这是用于创建和管理其他机器人的官方机器人。开始聊天并发送 /newbot 命令。
BotFather 随后会依次询问两件事：
- 你的机器人的显示名称，例如“我的第一个 API 机器人”。
- 一个以
bot结尾的用户名，例如first_api_demo_bot。
完成后，BotFather 会返回一个 API 令牌，看起来像 123456789:AAExampleTokenStringHere。这个令牌是你完成本教程所需的唯一凭据。
注意： 任何拥有你令牌的人都可以控制你的机器人。请将其保存在环境变量中，而不是源代码中。如果令牌泄露，请向 BotFather 发送
/revoke以获取新的令牌。
第二步：调用你的第一个 Bot API 方法
在编写任何程序之前，请确认令牌是否有效。getMe 方法返回有关你机器人的基本信息，是标准的健康检查方法。将 <YOUR_TOKEN> 替换为 BotFather 提供的值。
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe成功的响应将是 JSON 格式，其中包含 "ok": true 以及你机器人的 ID、名称和用户名。如果你看到 "ok": false，则表示令牌错误或有拼写错误。
这一个请求就是整个模式。每个 Telegram Bot API 方法都遵循相同的形式：对 https://api.telegram.org/bot<TOKEN>/METHOD_NAME 进行 HTTPS 调用，参数通过查询字符串或 POST 正文传递，并返回一个 JSON 对象。完整的列表可以在 Bot API 参考中找到，其中记录了你可能需要的所有方法和对象。
第三步：接收和发送消息
现在让机器人变得有用起来。有一个规则会让初学者感到惊讶：机器人不能主动发起对话。用户必须先给机器人发消息。所以，在 Telegram 中打开你的机器人并发送任意文本，例如“你好”。
接下来，使用 getUpdates 读取该消息，它通过长轮询获取传入的更新并返回一个更新对象数组。
curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates在响应中，找到 message.chat.id。这个 chat_id 就是你回复的地址。复制它，然后调用 sendMessage：
curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
-d chat_id=<CHAT_ID> \
-d text="我的第一个机器人向你问好"你的机器人会在聊天中回复。这个往返过程，即用 getUpdates 读取并用 sendMessage 回复，是大多数 Telegram 机器人背后的核心循环。text 参数接受每条消息最多 4096 个字符，因此较长的回复需要拆分。
将此 Telegram 机器人 API 示例扩展到实际代码时，请记住两个细节：
- 重新计算偏移量。 在下一次
getUpdates调用时，将上次更新的update_id加一作为offset参数传递，否则 Telegram 会一直返回相同的更新。 - 一次只使用一种方法。 一旦你注册了 Webhook，
getUpdates就会停止工作，这是下一步的主题。
第四步：选择长轮询或 Webhook
Telegram 提供了两种接收更新的方式，并且你一次只能为每个机器人使用其中一种。
- 长轮询 意味着你的代码会重复调用
getUpdates。对于学习和本地开发来说，这是最简单的方式，因为它不需要公共 URL，只需要一个持续运行的进程。 - Webhook 意味着 Telegram 会在更新发生的那一刻，将每个更新作为 POST 请求推送到你的 HTTPS 端点。这是生产环境的标准：延迟更低，没有空闲轮询，并且在稳定流量下扩展性更好。
要切换到 Webhook，请注册你的公共 HTTPS URL 一次：
curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"你的端点需要有效的 TLS 证书，并且必须快速返回 HTTP 200。如果更新停止到达，第一步总是检查错误。有关完整的注册、验证和故障排除流程，请参阅我们的 Telegram 机器人 Webhook 设置指南。简而言之：在构建时使用轮询，在发布前切换到 Webhook。
第五步：用库封装 API
原始的 cURL 对于学习来说很棒，但生产环境的机器人会使用库。库会处理 API 调用、更新解析、重试和对话状态，因此你只需编写机器人特有的逻辑。Telegram 在其 Bot API 示例页面上列出了几乎所有语言的社区库。
根据你已经熟悉的语言进行选择：
- Python：
python-telegram-bot是纯 Python 编写的，完全异步，支持 Python 3.10 及更高版本。aiogram和pyTelegramBotAPI也是流行的替代品。 - Node.js：
Telegraf成熟且对 TypeScript 友好。node-telegram-bot-api是一个长期存在的选项。
以下是 Python 中相同的回声机器人，这是 Telegram 机器人 API Python 教程中最常见的起点：
from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes
TOKEN = "YOUR_TOKEN"
async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
await update.message.reply_text(update.message.text)
app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()以及使用 Telegraf 的 Node.js 等效代码：
import { Telegraf } from 'telegraf'
const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()两者都完成了第三步中 cURL 循环的相同工作，但代码更少，并且为你处理了繁琐的部分。Maria 是一名后端开发人员，她正在为支持机器人制作原型，她在下午从 cURL 测试转向 python-telegram-bot，并在同一天就实现了命令处理程序和内联按钮。API 概念直接沿用，因为库只是相同 HTTP 方法的薄封装。
需要了解的速率限制和配额
API 是免费的，但并非没有限制。Telegram 的 Bots FAQ 列出了防止你的机器人被限流的指导原则。
- 每个聊天每秒一条消息。 在单个对话中，避免发送速度超过此限制。
- 向许多不同用户发送时，总计大约每秒 30 条消息。 超过此限制，你将开始收到 HTTP 429 “Too Many Requests” 响应。
- 向同一群组发送时，大约每分钟 20 条消息。
当广播确实需要更多消息时，你可以在 @BotFather 中启用付费广播，这将把上限提高到每秒 1000 条消息。超出免费的每秒 30 条消息的额外消息，每条将花费 0.1 Telegram Stars。大多数机器人永远不需要这个功能，但在设计通知功能之前了解这个限制是好的。
遇到 429 错误时，请读取 Telegram 返回的 retry_after 值，并暂停相应秒数。库会为你处理这个问题，这也是当你的流量真实时，从原始请求升级到使用库的另一个原因。
跳过代码：无需服务器的 AI 机器人
并非每个项目都需要自定义代码库。如果你的目标是在 Telegram 群组中实现 AI 助手，那么 Bot API 可能是一个你不想自己维护的底层设施，尤其是托管、HTTPS 和 Webhook 层。
TeleClaw 是一个无代码平台，可以为你运行机器人并开箱即用地连接 Claude AI。你只需将 @claw 添加到你的群组，将你的 BotFather 令牌粘贴到仪表板中，然后配置行为，而无需触及 setWebhook 或速率限制处理。Tomas 运营着一个拥有 4,000 名成员的加密社区，他用 TeleClaw 替换了一个半成品自定义机器人，并在当晚就实现了 AI 审核和常见问题解答功能。
底层仍然是相同的 Bot API。你只是在选择是自己操作服务器层，还是让平台来完成。在 TeleClaw 功能页面上探索它涵盖了哪些内容，并在我们的最佳 Telegram 机器人综述中比较各种选项。对于纯粹的仪表板构建，请参阅我们的无代码 Telegram 聊天机器人指南。
总结
你现在已经对 Telegram Bot API 有了一个清晰的理解：从 BotFather 获取令牌，使用 getMe、getUpdates 和 sendMessage 等 HTTP 方法，在长轮询和 Webhook 之间做出选择，以及当你的机器人发展壮大时，使用库来封装所有功能。这个 API 是免费的，文档完善，并且足够友好，可以在几分钟内用 cURL 进行测试。
最快的下一步是最小的一步。打开 @BotFather，运行 /newbot，然后发送你的第一个 getMe 请求以确认令牌。从那里，你可以在 Python 或 Node 中构建，或者完全跳过服务器。要快速启动一个 AI 驱动的机器人，只需将 @claw 添加到你的群组，并在 TeleClaw 仪表板中进行配置。
FAQ
