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})

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})

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 bot instance.

final

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

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

Adds a handler for callback queries with specific data.

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

Adds a handler for specific chat type.

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

Adds a handler for multiple chat types.

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.

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

Adds a handler for multiple entity types.

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

Adds a handler for specific entity types.

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<Context> predicate, UpdateHandler<CTX> handler) → Bot<CTX>

Adds a handler for matching a custom filter

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

Adds middleware that runs concurrently (fork).

override

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.

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

Adds a handler for /help command.

initialize() → Future<BotInfo>

Initializes the bot.

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

Adds a handler for inline queries with specific data.

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.

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

Adds a handler for messages with animations.

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

Adds a handler for messages with audio files.

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

Adds a handler for business connection updates.

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

Adds a handler for business message updates.

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

Adds a handler for deleted business message updates.

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

Adds a handler for edited business message updates.

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

Adds a handler for callback queries.

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

Adds a handler for messages with captions.

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

Adds a handler for channel post updates.

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

Adds a handler for chat boost updates.

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

Adds a handler for chat boost removal updates.

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

Adds a handler for chat join request updates.

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

Adds a handler for chat member updates.

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

Adds a handler for chat shared messages.

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

Adds a handler for chosen inline result updates.

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

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

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

Adds a handler for messages with contacts.

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

Adds a handler for delete chat photo service messages.

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

Adds a handler for messages with dice.

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

Adds a handler for messages with documents.

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

Adds a handler for edited channel post updates.

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

Adds a handler for edited message updates.

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

Adds a handler for messages with email entities.

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.

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

Adds a handler for forum topic created service messages.

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

Adds a handler for forum topic edited service messages.

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

Adds a handler for forum topic reopened service messages.

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

Adds a handler for messages with games.

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

Adds a handler for group chat messages.

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

Adds a handler for messages with hashtag entities.

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

Adds a handler for inline queries.

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

Adds a handler for messages with live location updates.

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

Adds a handler for messages with location data.

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

Adds a handler for messages with mention entities.

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

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

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

Adds a handler for message reaction updates.

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

Adds a handler for message reaction count updates.

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

Adds a handler for bot's chat member updates.

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

Adds a handler for new chat photo service messages.

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

Adds a handler for new chat title service messages.

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

Adds a handler for paid media messages.

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

Adds a handler for paid media with photos.

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

Adds a handler for paid media purchase updates.

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

Adds a handler for paid media with videos.

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

Adds a handler for messages with phone number entities.

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

Adds a handler for messages with photos.

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

Adds a handler for pinned message service messages.

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

Adds a handler for poll updates.

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

Adds a handler for poll answer updates.

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

Adds a handler for messages with polls.

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

Adds a handler for pre-checkout query updates.

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

Adds a handler for private chat messages.

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

Adds a handler for shipping query updates.

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

Adds a handler for messages with stickers.

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

Adds a handler for successful payment messages.

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

Adds a handler that runs for any text message.

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

Adds a handler for messages with URL entities.

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

Adds a handler for user shared messages.

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

Adds a handler for messages with venue information.

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

Adds a handler for messages with video files.

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

Adds a handler for messages with video notes.

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

Adds a handler for messages with voice notes.

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

Adds a handler for web app data messages.

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.

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).

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.

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

Adds a handler for video chat ended service messages.

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

Adds a handler for video chat participants invited service messages.

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

Adds a handler for video chat scheduled service messages.

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

Adds a handler for video chat started service messages.

Operators

operator ==(Object other) → bool

The equality operator.

inherited