getUpdates

Retrieve the latest updates for the Bot using long polling. Returns an array of Update objects.

Request

GET /:token/getUpdates

POST /:token/getUpdates

This method supports both GET and POST requests.

Parameters

Parameter	Type	Required	Description
offset	Integer	No	Update offset. Pass the most recent update_id + 1 to receive only updates after that offset
limit	Integer	No	Maximum number of updates to be returned. Values between 1-100 are accepted, defaults to 100
timeout	Integer	No	Long polling timeout in seconds. Set to 0 for immediate response. Recommended value is around 30 to reduce request frequency
allowed_updates	String[]	No	List of allowed update types to receive, e.g. ["message", "callback_query"]

Response

Returns an array of Update objects. If there are no new updates, an empty array is returned.

{
  "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 Object Fields

Field	Type	Description
update_id	Integer	Unique identifier for the update, incrementing
message	Message	Optional. New incoming message
callback_query	CallbackQuery	Optional. Callback query

Error Codes

Code	Description
400	Bad request parameters, e.g. invalid offset format
401	Invalid or expired token
409	Conflict, possibly because a webhook is already set and long polling cannot be used simultaneously
500	Internal server error

Example

cURL

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

Response When No Updates

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