Bot<CTX extends Context> class

The main Bot class for creating and managing Telegram bots.

This class provides a high-level, type-safe interface for building Telegram bots. It extends Composer to provide middleware composition capabilities and includes methods for handling different types of updates with full generic support.

The Bot class supports:

• Generic context types for type safety
• Middleware composition and error handling
• Multiple update fetching strategies (long polling, webhooks)
• Filter-based update routing
• Plugin system for extensibility
• Comprehensive error handling

Example:

final bot = Bot<Context>('YOUR_BOT_TOKEN');

bot.command('start', (ctx) async {
  await ctx.reply('Hello! Welcome to my bot.');
});

bot.hears('hello', (ctx) async {
  await ctx.reply('Hi there! 👋');
});

bot.catch((error) async {
  print('Bot error: ${error.error}');
});

await bot.start();

Inheritance

• Object
• Composer<CTX>
• Bot

Constructors

Bot(String token, {ContextFactory<CTX>? contextFactory, BotInfo? botInfo, HttpClient? httpClient, String? baseUrl, bool isTest = false})

Creates a new Bot instance.

Bot.fromAPI(RawAPI api, {ContextFactory<CTX>? contextFactory, BotInfo? botInfo})

Creates a Bot instance from an existing RawAPI instance.

factory

Bot.local(String token, String url, {ContextFactory<CTX>? contextFactory, BotInfo? botInfo, HttpClient? httpClient, bool isTest = false})

Creates a Bot instance for use with a local Bot API server.

factory

Properties

api → RawAPI

The RawAPI instance for making Telegram Bot API calls.

final

botInfo ↔ BotInfo

Information about the bot.

getter/setter pair

currentFetcher → UpdateFetcher?

Gets the current update fetcher.

no setter

filters → Filters<CTX>

Context-aware filters for this composer instance.

final, inherited

hasErrorHandling → bool

Checks if the composer has error handling configured.

no setter, inherited

hashCode → int

The hash code for this object.

no setter, inherited

hasMiddleware → bool

Checks if the composer has any middleware.

no setter, inherited

isInitialized → bool

Whether the bot has been initialized.

no setter

isRunning → bool

Whether the bot is currently running.

no setter

me → BotInfo

Information about the bot.

no setter

middlewareCount → int

Gets the number of middleware in this composer.

no setter, inherited

middlewareNames → List<String>

Gets the list of middleware names (where available).

no setter, inherited

plugins → List<BotPlugin<CTX>>

Gets the list of installed plugins.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

stats → BotStats

Gets the bot's current statistics.

no setter

token → String

The bot token used for authentication.

final

Methods

attachMenu(TeleverseMenu<CTX> menu) → Bot<CTX>

Attaches a menu to this bot.

branch(MiddlewarePredicate<CTX> predicate, Middleware<CTX> trueMiddleware, Middleware<CTX> falseMiddleware) → Bot<CTX>

Adds middleware that handles a specific branch of execution.

override

call(CTX ctx, NextFunction next) → Future<void>

Makes the Composer callable as middleware.

inherited

callbackQuery(Pattern data, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for callback queries with specific data.

override

chatType(ChatType chatType, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for specific chat type.

override

chatTypes(Set<ChatType> chatTypes, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for multiple chat types.

override

clear() → Bot<CTX>

Removes all middleware from this composer.

override

clone() → Composer<CTX>

Clones this composer.

inherited

close() → Future<void>

Closes the bot and releases all resources.

command(String command, UpdateHandler<CTX> handler, {bool caseSensitive = false}) → Bot<CTX>

Adds a handler for a specific command.

override

entities(Set<MessageEntityType> entityTypes, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for multiple entity types.

override

entity(MessageEntityType entityType, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for specific entity types.

override

errorBoundary(ErrorBoundaryHandler<CTX> errorHandler, [List<Middleware<CTX>> protectedMiddleware = const []]) → Bot<CTX>

Creates an error boundary that catches errors from specific middleware.

override

errorBoundaryVarArgs(ErrorBoundaryHandler<CTX> errorHandler, Middleware<CTX> middleware1, [Middleware<CTX>? middleware2, Middleware<CTX>? middleware3, Middleware<CTX>? middleware4, Middleware<CTX>? middleware5]) → Bot<CTX>

Alternative error boundary method that accepts middleware as varargs.

override

extend(List<Middleware<CTX>> additionalMiddleware) → Composer<CTX>

Creates a sub-composer with additional middleware.

inherited

filter(MiddlewarePredicate<CTX> predicate, [UpdateHandler<CTX>? handler]) → Composer<CTX>

Adds a handler for matching a custom filter

override

fork(Middleware<CTX> middleware) → Bot<CTX>

Adds middleware that runs concurrently (fork).

override

group([String? name]) → Composer<CTX>

Creates a new handler group.

inherited

handle(CTX ctx) → Future<bool>

Processes a context through the middleware chain.

inherited

handleUpdate(Update update) → Future<void>

Handles an incoming update.

hears(Pattern pattern, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for text messages that match a pattern.

override

help(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for /help command.

override

initialize() → Future<BotInfo>

Initializes the bot.

inlineQuery(Pattern query, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for inline queries with specific data.

override

insertAt(int index, Middleware<CTX> middleware) → Bot<CTX>

Inserts middleware at a specific position.

override

lazy(MiddlewareFactory<CTX> middlewareFactory) → Bot<CTX>

Adds middleware that is created lazily based on the context.

override

mount(Composer<CTX> other) → Bot<CTX>

Mounts another composer's middleware.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

on(Filter<CTX> filter, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler using a custom filter.

override

onAnimation(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with animations.

override

onAudio(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with audio files.

override

onBusinessConnection(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for business connection updates.

override

onBusinessMessage(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for business message updates.

override

onBusinessMessageDeleted(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for deleted business message updates.

override

onBusinessMessageEdited(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for edited business message updates.

override

onCallbackQuery(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for callback queries.

override

onCaption(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with captions.

override

onChannelPost(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for channel post updates.

override

onChatBoosted(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for chat boost updates.

override

onChatBoostRemoved(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for chat boost removal updates.

override

onChatJoinRequest(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for chat join request updates.

override

onChatMember(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for chat member updates.

override

onChatShared(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for chat shared messages.

override

onChosenInlineResult(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for chosen inline result updates.

override

onCommand(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for any command (equivalent to onCommand).

override

onContact(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with contacts.

override

onDeleteChatPhoto(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for delete chat photo service messages.

override

onDice(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with dice.

override

onDocument(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with documents.

override

onEditedChannelPost(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for edited channel post updates.

override

onEditedMessage(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for edited message updates.

override

onEmail(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with email entities.

override

onError(ErrorHandler<CTX> handler) → Bot<CTX>

Sets a global error handler that catches all unhandled errors.

override

onForumTopicClosed(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for forum topic closed service messages.

override

onForumTopicCreated(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for forum topic created service messages.

override

onForumTopicEdited(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for forum topic edited service messages.

override

onForumTopicReopened(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for forum topic reopened service messages.

override

onGame(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with games.

override

onGroupChat(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for group chat messages.

override

onHashtag(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with hashtag entities.

override

onInlineQuery(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for inline queries.

override

onLiveLocation(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with live location updates.

override

onLocation(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with location data.

override

onMention(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with mention entities.

override

onMessage(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for any message update (regular or edited).

override

onMessageReaction(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for message reaction updates.

override

onMessageReactionCount(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for message reaction count updates.

override

onMyChatMember(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for bot's chat member updates.

override

onNewChatPhoto(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for new chat photo service messages.

override

onNewChatTitle(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for new chat title service messages.

override

onPaidMedia(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for paid media messages.

override

onPaidMediaPhoto(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for paid media with photos.

override

onPaidMediaPurchase(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for paid media purchase updates.

override

onPaidMediaVideo(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for paid media with videos.

override

onPhoneNumber(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with phone number entities.

override

onPhoto(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with photos.

override

onPinnedMessage(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for pinned message service messages.

override

onPoll(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for poll updates.

override

onPollAnswer(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for poll answer updates.

override

onPollMessage(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with polls.

override

onPreCheckoutQuery(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for pre-checkout query updates.

override

onPrivateChat(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for private chat messages.

override

onShippingQuery(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for shipping query updates.

override

onSticker(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with stickers.

override

onStop(FutureOr<void> onStop()?) → Bot<CTX>

Sets the on stop handler for this bot.

onSuccessfulPayment(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for successful payment messages.

override

onText(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler that runs for any text message.

override

onURL(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with URL entities.

override

onUsrShared(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for user shared messages.

override

onVenue(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with venue information.

override

onVideo(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with video files.

override

onVideoNote(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with video notes.

override

onVoice(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for messages with voice notes.

override

onWebAppData(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for web app data messages.

override

plugin(BotPlugin<CTX> plugin) → Bot<CTX>

Installs a plugin.

removeAt(int index) → Bot<CTX>

Removes middleware at a specific index.

override

removeNamed(String name) → Bot<CTX>

Removes middleware with a specific name.

override

settings(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for /settings command.

override

start([UpdateFetcher? fetcher]) → Future<void>

Starts the bot with the specified fetcher.

startWebhook({required String webhookUrl, int port = 8080, String? secretToken, String? healthCheckPath = '/health', bool corsEnabled = true, String? bindAddress, String webhookPath = '/webhook', int maxConnections = 40, bool dropPendingUpdates = false, List<UpdateType>? allowedUpdates}) → Future<void>

Starts the bot with a built-in webhook server.

startWebhookDev(String ngrokUrl, {int port = 8080, String webhookPath = '/webhook'}) → Future<void>

Starts the bot with webhook for ngrok development.

stop() → Future<void>

Stops the bot.

text(String text, UpdateHandler<CTX> handler, {bool caseSensitive = true}) → Bot<CTX>

Adds a handler with exact text matching (alias for textEquals).

override

toString() → String

A string representation of this object.

override

use(Middleware<CTX> middleware) → Bot<CTX>

Adds middleware to the composition.

override

useNamed(String name, Middleware<CTX> middleware) → Bot<CTX>

Adds named middleware to the composition.

override

when(MiddlewarePredicate<CTX> predicate, Middleware<CTX> middleware) → Bot<CTX>

Adds conditional middleware that only runs when a predicate is true.

override

whenMentioned(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for when the bot is mentioned.

whenReacted(String emoji, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for specific emoji reactions.

override

whenVideoChatEnded(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for video chat ended service messages.

override

whenVideoChatParticipantsInvited(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for video chat participants invited service messages.

override

whenVideoChatScheduled(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for video chat scheduled service messages.

override

whenVideoChatStarted(UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for video chat started service messages.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited