getUpdates

Returns: Update[]Official docs ↗

Use this method to receive incoming updates using long polling (wiki). Returns an Array of Update objects.

Parameters

offsetIntegerOptional

Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with an offset higher than its update\_id. The negative offset can be specified to retrieve updates starting from \-offset update from the end of the updates queue. All previous updates will be forgotten.

limitIntegerOptional Default: 100min 1max 100

Limits the number of updates to be retrieved. Values between 1-100 are accepted. Defaults to 100.

timeoutIntegerOptional Default: 0

Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling. Should be positive, short polling should be used for testing purposes only.

allowed_updatesString[]Optional

A JSON-serialized list of the update types you want your bot to receive. For example, specify ["message", "editedchannelpost", "callbackquery"] to only receive updates of these types. See Update for a complete list of available update types. Specify an empty list to receive all update types except chat\member, message\reaction, and message\reaction\_count (default). If not specified, the previous setting will be used. Please note that this parameter doesn't affect updates created before the call to getUpdates, so unwanted updates may be received for a short period of time.

Returns

On success, an array of Update objects is returned.

GramIO Usage

GramIO handles long polling automatically when you call bot.start(). Direct bot.api.getUpdates() calls are useful for manual polling loops, debugging, or consuming a specific offset.

// GramIO uses long polling automatically — just start the bot:
bot.command("start", (ctx) => ctx.send("Hello!"));

bot.start();

// Filter update types to reduce traffic — only receive messages and callbacks:
const updates = await bot.api.getUpdates({
  timeout: 30,
  allowed_updates: ["message", "callback_query"],
  limit: 100,
});

// Acknowledge (confirm) all pending updates by sending a high offset:
// This discards any queued updates before the bot (re)starts.
await bot.api.getUpdates({ offset: -1 });

// Manual polling loop with proper offset tracking:
let offset = 0;

while (true) {
  const updates = await bot.api.getUpdates({ offset, timeout: 30, limit: 100 });

  for (const update of updates) {
    console.log("Received update:", update.update_id);
    offset = update.update_id + 1; // Confirm each update
  }
}

Errors

Code	Error	Cause
409	Conflict: can't use getUpdates method while webhook is active	A webhook is set — call deleteWebhook first, or switch to webhook mode
429	Too Many Requests: retry after N	Polling too fast — use a positive timeout value for long polling and check retry_after

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Cannot coexist with a webhook. getUpdates returns a 409 error if a webhook is active. Run deleteWebhook before switching to polling, or setWebhook before switching to webhooks.
• Set timeout > 0 for real long polling. timeout: 0 is short polling and hammers Telegram's servers — use 30–60 seconds in production. GramIO's bot.start() configures this automatically.
• Offset confirmation is critical. An update is only "consumed" once getUpdates is called with an offset strictly higher than its update_id. Failing to advance the offset will re-deliver the same updates indefinitely.
• allowed_updates does not apply retroactively. Updates created before the parameter change may still arrive briefly. Omitting allowed_updates preserves the previous setting — send an explicit list on first boot.
• Empty allowed_updates: [] excludes three types by default: chat_member, message_reaction, and message_reaction_count are excluded when passing an empty array — opt in explicitly if you need them.
• Negative offset tricks. Passing offset: -1 returns the single most recent update without consuming the others, useful for a quick "peek" or startup flush.

See Also

• Update — full shape of every update object returned
• setWebhook — alternative update delivery via HTTPS push
• deleteWebhook — required before switching from webhook to polling
• getWebhookInfo — check current webhook configuration
• Updates overview — GramIO polling vs. webhook guide