Receiving Updates

Part of the API Reference.

getUpdates

Future<List<Update>> getUpdates({
    int? offset,
    int? limit,
    int? timeout,
    List<String>? allowedUpdates,
  }) async {

Long-polls Telegram for new [Update]s.

You rarely need to call this directly — prefer the [poll] stream, which wraps this method in a convenient await for loop and manages the offset for you automatically.

Typed helpers & Update shortcuts

Every raw field on an Update is reachable directly, but two things make working with them more convenient:

Update shortcuts. Update exposes direct-access getters — chatId, userId, text, caption, messageId, messageThreadId, replyToMessage, and more — computed across whichever kind of payload the update actually carries (message, editedMessage, channelPost, callback queries, and so on) via the underlying anyMessage fallback. This is what lets the getting-started example write update.text and update.chatId without first checking which update field is populated. As of 1.1.0 this also covers subscription (paired with UpdateType.subscription) for changes to a user's Telegram Stars subscription to the bot's content, plus shortcuts for the new guest-query and chat-join-request-webapp flows.

Typed wrappers. User, Chat, and Message are thin, read-only, lossless wrappers around the raw JSON Update already hands you — construct one from any matching Json you have (User(update.from!)) to get typed getters (id, firstName, isPremium, ...) instead of manual as casts, with the original raw map always available underneath for anything not covered by a getter. Wrapping is entirely optional; the raw-JSON style shown throughout this reference still works exactly as before.

See example/18_typed_message_helpers.dart and example/19_update_shortcuts_and_any_message.dart for runnable versions of both.

setWebhook

Future<bool> setWebhook(
    String url, {
    InputFile? certificate,
    String? ipAddress,
    int? maxConnections,
    List<String>? allowedUpdates,
    bool? dropPendingUpdates,
    String? secretToken,
  }) async =>

Registers [url] as the webhook endpoint Telegram will POST updates to. Use [serveWebhook] on your side to actually receive them.

deleteWebhook

Future<bool> deleteWebhook({bool? dropPendingUpdates}) async => _b(await call('deleteWebhook', {
        if (dropPendingUpdates != null) 'drop_pending_updates': dropPendingUpdates,
      }),);

Removes the current webhook and switches the bot back to polling mode.

getWebhookInfo

Future<Json> getWebhookInfo() async => _o(await call('getWebhookInfo'));

Returns the current webhook status (URL, pending update count, last error, etc).

serveWebhook

Future<HttpServer> serveWebhook(
    void Function(Update update) onUpdate, {
    String path = '/',
    Object address = '0.0.0.0',
    int port = 8443,
    SecurityContext? securityContext,
    String? secretToken,
  }) async {

Starts an HTTP server that receives Telegram webhook updates and calls [onUpdate] for each one. Alternative to [poll] for production deployments behind a reverse proxy or with a direct TLS certificate via [securityContext]. Pair with [setWebhook] so Telegram knows where to send updates.