getUpdates

通过长轮询方式获取 Bot 的最新更新。返回 Update 对象数组。

请求

GET /:token/getUpdates

POST /:token/getUpdates

本方法同时支持 GET 和 POST 请求。

参数

参数	类型	必填	描述
offset	Integer	否	更新偏移量。传入已处理的最新 update_id + 1，服务端将只返回该偏移量之后的更新
limit	Integer	否	限制返回的更新数量，取值范围 1-100，默认 100
timeout	Integer	否	长轮询超时时间（秒）。设为 0 表示立即返回，建议设为 30 左右以减少请求频率
allowed_updates	String[]	否	允许接收的更新类型列表，例如 ["message", "callback_query"]

响应

返回 Update 对象数组。如果没有新的更新，返回空数组。

{
  "ok": true,
  "result": [
    {
      "update_id": 100000001,
      "message": {
        "message_id": 1,
        "from": {
          "id": 987654321,
          "is_bot": false,
          "first_name": "User",
          "username": "user123"
        },
        "chat": {
          "id": 987654321,
          "first_name": "User",
          "username": "user123",
          "type": "private"
        },
        "date": 1700000000,
        "text": "Hello, Bot!"
      }
    }
  ]
}

Update 对象字段说明

字段	类型	描述
update_id	Integer	更新的唯一标识符，递增
message	Message	可选，新收到的消息
edited_message	Message	可选，已编辑的消息
channel_post	Message	可选，频道新消息
edited_channel_post	Message	可选，频道已编辑的消息
business_connection	BusinessConnection	可选，Bot 与商业帐户之间的连接状态变更
business_message	Message	可选，通过商业帐户收到的新消息
edited_business_message	Message	可选，通过商业帐户编辑的消息
deleted_business_messages	DeletedBusinessMessages	可选，通过商业帐户删除的消息
message_reaction	MessageReactionUpdated	可选，消息回应变更
message_reaction_count	MessageReactionCountUpdated	可选，匿名消息回应计数变更
inline_query	InlineQuery	可选，收到的内联查询
chosen_inline_result	ChosenInlineResult	可选，用户选择的内联查询结果
callback_query	CallbackQuery	可选，回调查询
shipping_query	ShippingQuery	可选，收到的配送查询
pre_checkout_query	PreCheckoutQuery	可选，收到的预结账查询
purchased_paid_media	PurchasedPaidMedia	可选，付费媒体购买信息
poll	Poll	可选，投票状态变更
poll_answer	PollAnswer	可选，用户投票答案变更
my_chat_member	ChatMemberUpdated	可选，Bot 自身的聊天成员状态变更
chat_member	ChatMemberUpdated	可选，其他聊天成员状态变更
chat_join_request	ChatJoinRequest	可选，加入聊天请求
chat_boost	ChatBoostUpdated	可选，聊天 Boost 变更
removed_chat_boost	ChatBoostRemoved	可选，聊天 Boost 被移除

错误码

错误码	描述
400	请求参数错误，如 offset 格式不正确
401	Token 无效或已过期
409	存在冲突，可能是 Webhook 已设置，无法同时使用长轮询
500	服务器内部错误

示例

cURL

curl -X POST "https://api.example.com/<token>/getUpdates" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 100000002,
    "limit": 10,
    "timeout": 30
  }'

无更新时的响应

{
  "ok": true,
  "result": []
}