Context Class

The Context class is arguably the most important component you'll interact with when building a bot. Whenever Televerse receives an update from Telegram, it wraps that update in a Context object.

This object does three things:

• Holds the Update data (message, callback query, etc.).
• Provides convenient "shortcuts" or getters to access common data.
• Exposes methods to reply or perform actions in the context of that update.

Core Properties

Every context instance exposes these fundamental properties:

Smart Getters

Telegram updates can be complex. A "text message" might come from a private chat, a group, a channel post, or even an edited message. The Context class provides smart getters that abstract away this complexity.

// Instead of:
// final text = ctx.update.message?.text ?? 
//             ctx.update.channelPost?.text ?? 
//             ctx.update.callbackQuery?.message?.text;

// You can simply use:
final text = ctx.text;

// Instead of checking multiple places for the user:
final user = ctx.from;

Common Getters

• ctx.msg

  The effective message. Checks message, editedMessage, channelPost, etc.

• ctx.from

  The user who triggered the update. Works for messages, callbacks, inline queries, etc.

• ctx.chat

  The conversation where the update happened.

• ctx.text

  The text content of the message or caption.

Context-Aware Methods

Instead of using bot.api.sendMessage(chatId, "Hello") and manually passing the chat ID,Context provides methods that "know" where to reply.

bot.command('start', (ctx) async {
  // Simple reply (auto-detects chat ID)
  await ctx.reply("Hello! 👋");
  
  // Reply with photo
  final photo = InputFile.fromFile(File('welcome.jpg'));
  await ctx.replyWithPhoto(photo, caption: "Welcome to the bot!");
  
  // Send a sticker
  await ctx.replyWithSticker(
    InputFile.fromFileId('CAACAgIAAxkBAAIEal...'),
  );
});

Available methods include reply, replyWithPhoto, replyWithAudio, replyWithVideo,replyWithDocument, replyWithSticker, replyWithLocation, and many more.

Command Parsing

When dealing with commands, Context automatically parses the command and its arguments.

// User sends: /ban @baduser spamming

bot.command('ban', (ctx) {
  // ctx.command -> "ban"
  
  // ctx.args -> ["@baduser", "spamming"]
  final target = ctx.args[0];
  final reason = ctx.args.sublist(1).join(' ');
  
  ctx.reply("Banning $target for $reason");
});

Pattern Matching

If you use bot.hears with a RegExp, the matches are automatically stored in the context.

// Match email addresses
bot.hears(RegExp(r'[a-zA-Z0-9._]+@[a-z]+.[a-z]+'), (ctx) {
  // Access the matches
  final email = ctx.matches.first.group(0);
  
  ctx.reply("Found email: $email");
});

Passing Data (Middleware)

You can use the Context to pass data between middlewares. This is useful for authentication, session management, or passing database objects to your handlers.

// In your authentication middleware
bot.use((ctx, next) async {
  final user = await database.getUser(ctx.from?.id);
  
  // Store user data in context
  ctx.set('db_user', user);
  
  await next();
});

// In your command handler
bot.command('profile', (ctx) {
  // Retrieve the data
  final user = ctx.get<UserConfig>('db_user');
  
  ctx.reply("Hello ${user.name}!");
});

Next Steps

• Bot Class- Learn about the main Bot class.
• Middleware- Dive deeper into the middleware system.