Telegram Bot API 开发入门：Token、getUpdates 和 Webhook 基本概念

机器人 · 更新于 2026-10-20 · Bot API / 开发 / 机器人

写 Telegram 机器人的门槛其实很低：不用申请、不用审核，几分钟就能拿到一个能收发消息的机器人。难的是一开始那几个概念，搞明白了，后面换什么语言、什么框架都是一样的套路。

这篇不绑定任何框架，用 HTTP 请求直接讲。代码只是示意，生产环境请用成熟的库。

第一步：用 @BotFather 创建机器人

@BotFather 是 Telegram 官方用来管理机器人的机器人。私聊它：

发 /newbot
按提示输入机器人的显示名称（随便起，可以中文）
再输入用户名，必须以 bot 结尾，比如 my_test_bot，不能和别人重复

成功后 BotFather 会给你一串 Token，格式类似 123456789:AAH...。前面的数字是机器人 ID，后面是密钥。

Token 就是机器人的全部权限。 谁拿到 Token 谁就能完全控制这个机器人。别把它提交到公开的 GitHub 仓库，别贴到群里问问题。万一泄露了，在 BotFather 里发 /revoke 重新生成，旧的立即失效。

BotFather 里还有不少常用设置：/setdescription 改介绍、/setcommands 设置命令列表、/setprivacy 改隐私模式、/setinline 开启内联模式，发 /help 能看到全部。

Bot API 长什么样

Bot API 就是一组 HTTPS 接口，地址格式固定：

https://api.telegram.org/bot<Token>/<方法名>

注意 bot 和 Token 之间没有斜杠。可以先用浏览器或 curl 试一下 getMe，它返回机器人自己的信息：

curl https://api.telegram.org/bot<Token>/getMe

返回的是 JSON，"ok": true 说明 Token 没问题。所有方法都是这个模式，参数可以放在 URL 查询串里，也可以用 POST 发 JSON。

核心概念：Update

机器人不会"看见"聊天界面，它收到的是一条条 Update（更新）。有人给它发消息、点了按钮、把它拉进群、发了内联查询，都会产生一个 Update。

一个最常见的 Update 大概是这样（省略了很多字段）：

{
  "update_id": 100001,
  "message": {
    "message_id": 12,
    "from": { "id": 111222333, "first_name": "Alice" },
    "chat": { "id": 111222333, "type": "private" },
    "text": "/start"
  }
}

这里有两个 ID 要分清：

from.id：是谁发的
chat.id：发在哪个聊天里

私聊时两者相同；在群里，chat.id 是群的 ID（一般是负数），from.id 是发言的人。回复消息时要用 chat.id，这一点新手最容易搞混。

收消息的两种方式

机器人怎么拿到 Update？有两种方式，只能二选一。

轮询（getUpdates）：你的程序不停地去问 Telegram"有没有新消息"。适合开发调试、个人小机器人，不需要公网服务器，家里电脑就能跑。

调用时带上 offset 参数，值是上次收到的最大 update_id 加 1，表示"之前的都处理过了"。不带的话，会一直收到同样的旧消息。再加个 timeout 参数，变成长轮询，没消息时连接会挂着等一会儿，比狂刷接口省资源。

Webhook：你告诉 Telegram 一个 HTTPS 地址（setWebhook），有新消息时 Telegram 主动推过来。适合正式上线、消息量大的机器人。要求是公网可访问的 HTTPS，端口只能用 443、80、88、8443 之一。

设了 Webhook 之后再调 getUpdates 会报错，想切回轮询要先 deleteWebhook。这是调试时常见的"怎么突然收不到消息了"的原因。

最小可运行例子

下面用 Python 写一个复读机，收到什么就回什么。只用了 requests 库：

import requests, time

TOKEN = "你的Token"
API = f"https://api.telegram.org/bot{TOKEN}"
offset = 0

while True:
    r = requests.get(f"{API}/getUpdates",
                     params={"offset": offset, "timeout": 30}).json()
    for u in r.get("result", []):
        offset = u["update_id"] + 1
        msg = u.get("message")
        if msg and "text" in msg:
            requests.post(f"{API}/sendMessage", json={
                "chat_id": msg["chat"]["id"],
                "text": "你说的是：" + msg["text"],
            })
    time.sleep(1)

运行后私聊你的机器人，点开始，发一句话，它就会回你。

真要做项目，建议直接用社区成熟的库，比如 Python 的 python-telegram-bot、aiogram，Node.js 的 Telegraf、grammY。它们帮你处理好了轮询、重试、命令解析这些琐事。

新手常踩的坑

机器人不能主动找人。 用户没给机器人点过"开始"，机器人就不能给他发私聊消息，调用会返回错误。想做推送，必须让用户先 /start。

群里收不到普通消息。 机器人默认开着隐私模式，在群里只能收到命令、回复它的消息等。要收全部消息，在 BotFather 用 /setprivacy 关掉隐私模式，或者把机器人设为管理员。改了隐私模式后，可能需要把机器人移出群再重新拉进来才生效。

发得太快被限流。 官方的建议是：同一个聊天里每秒别超过 1 条；同一个群每分钟不超过 20 条；群发时整体每秒大约 30 条以内。超了会返回 429 错误，里面带有 retry_after，告诉你要等几秒。

文本太长发不出去。 单条文本消息最多 4096 个字符，超了要自己拆分。

文件大小有限制。 通过官方 Bot API 服务器，机器人下载文件最大 20MB、上传最大 50MB。需要处理大文件的，可以自己部署官方开源的 Bot API 服务器，限制会放宽很多。

格式化报错。 用 parse_mode 发 Markdown 或 HTML 格式时，特殊字符没转义会直接报 "can't parse entities"。MarkdownV2 需要转义的符号特别多，新手建议先用 HTML 模式。

Bot API 和"用户号机器人"不是一回事

有人会把 Bot API 和用 MTProto 协议、登录普通账号写的自动化脚本混为一谈。后者是用你的个人账号身份操作，能做的事更多，但滥用很容易导致账号被限制，也更容易踩到 Telegram 的使用条款。正常的机器人需求，用 Bot API 就够了。

做好的机器人，如果是公开可用的，可以提交到 DBQUN 让更多人看到，也可以去机器人导航看看同类机器人都做了哪些功能。想加内联模式，可以接着看内联机器人怎么用。