用长轮询接收消息和事件

不搭公网回调服务器，先读取 Webhook 状态，再用 getUpdates 获取消息。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

同一个机器人只使用一个长轮询消费者；getUpdates 与 Webhook 互斥。
仅对自己的测试机器人切换接收方式；生产中的 Webhook 不应被随意删除。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

TELEGRAM_BOT_TOKEN: 从 BotFather 新建机器人所得 Token；示例是假值。

export TELEGRAM_BOT_TOKEN='123456789:replace_with_bot_token'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
先读取 getWebhookInfo；如果 url 非空，继续使用已有 Webhook 或明确停用它，勿同时启动轮询。
02
测试用户发送 /start，再执行 getUpdates；本例只监听 message 与 callback_query。
03
处理并持久化本批更新后，用最大 update_id+1 作为下一次 offset。
04
长轮询应循环运行并持久保存 offset；本页代码是一次请求示例，不是常驻生产服务。

调用 01

检查 Webhook 状态

只读检查，不会删除或修改已有回调。

GEThttps://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo

参数说明

本接口无额外业务参数；按上方要求提供凭证。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo")
headers = {

}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "ok" in result and result["ok"] != True:
    raise SystemExit("平台返回业务错误，请结合下方排错说明检查响应")

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo");
const headers = Object.fromEntries(
  Object.entries({}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "ok") && result["ok"] !== true) {
  throw new Error('平台返回业务错误，请结合下方排错说明检查响应');
}

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。url 为空表示未配置 Webhook，pending_update_count 表示待处理数量。以下为结构示意，非本站实测结果。

{
  "ok": true,
  "result": {
    "url": "",
    "has_custom_certificate": false,
    "pending_update_count": 0
  }
}

常见错误与排查

ok=falseTelegram 拒绝请求: 读取 description 定位；Token 不正确、目标 chat 不可用及机器人被封禁需分别排查。
HTTP 429 / retry_after请求过快: 读取 parameters.retry_after，按秒等待，不立即重复请求。

调用注意

url 非空时不能 getUpdates；确认停用后才可调用 deleteWebhook，drop_pending_updates 不要误设 true。

getWebhookInfo

调用 02

接收一批 Update

timeout=20 开启长轮询；首次没有 offset，后续需主动确认上批更新。

POSThttps://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates

请求头

Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`timeout`请求体	integer可选	长轮询等待秒数；本例 20，小于代码 HTTP 超时。
`limit`请求体	integer可选	1–100，默认 100。
`offset`请求体	integer可选	下一次请求设为已持久化处理的最大 update_id+1；更高 offset 会确认之前的更新。
`allowed_updates`请求体	string[]可选	本例仅 message 和 callback_query；不填沿用之前配置，部分成员/反应事件需显式订阅。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cat > request-body.json <<'JSON'
{
  "timeout": 20,
  "limit": 100,
  "allowed_updates": [
    "message",
    "callback_query"
  ]
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates")
headers = {
    "Content-Type": expand("application/json"),
}
body = {
    "timeout": 20,
    "limit": 100,
    "allowed_updates": [
        "message",
        "callback_query",
    ],
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "ok" in result and result["ok"] != True:
    raise SystemExit("平台返回业务错误，请结合下方排错说明检查响应")

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates");
const headers = Object.fromEntries(
  Object.entries({
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "timeout": 20,
  "limit": 100,
  "allowed_updates": [
    "message",
    "callback_query"
  ]
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "ok") && result["ok"] !== true) {
  throw new Error('平台返回业务错误，请结合下方排错说明检查响应');
}

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。读取 result 数组；本例下一次 offset 应为 1002。以下为结构示意，非本站实测结果。

{
  "ok": true,
  "result": [
    {
      "update_id": 1001,
      "message": {
        "message_id": 40,
        "date": 1792022400,
        "chat": {
          "id": 123456789,
          "type": "private"
        },
        "from": {
          "id": 123456789,
          "is_bot": false,
          "first_name": "测试用户"
        },
        "text": "/start"
      }
    }
  ]
}

常见错误与排查

ok=falseTelegram 拒绝请求: 读取 description 定位；Token 不正确、目标 chat 不可用及机器人被封禁需分别排查。
HTTP 429 / retry_after请求过快: 读取 parameters.retry_after，按秒等待，不立即重复请求。
Webhook 已配置 / 另一个 getUpdates 正在运行接收方式或消费者冲突: 只保留一个消费者；先确认已有服务的用途，再更改配置。

调用注意

更新最多保留 24 小时；不是历史聊天导出接口。
按 update_id 去重，先完成业务与持久化再推进 offset，避免丢更新。

getUpdates

注意事项

群内可见内容还受隐私模式和管理员权限影响，不能假设机器人收到所有群消息。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
Bots: introduction for developers核验日期 2026-10-15
02
getUpdates核验日期 2026-10-15
03
getWebhookInfo核验日期 2026-10-15

Telegram 机器人的其他调用手册

验证机器人并发送文本发送按钮并回答点击回调

← 返回Telegram 机器人的全部功能