Bot Class

The Bot class is the central entity in the Televerse framework. It manages the connection to the Telegram Bot API, handles incoming updates, and dispatches them to your middleware and listeners. It extends the Composer class, giving it full access to all middleware and filter capabilities.

Initialization

To start using Televerse, you simply need to create an instance of the Bot class with your bot token. You can also specify a custom Context type for type-safe middleware.

import 'package:televerse/televerse.dart';

void main() {
  // Basic initialization
  final bot = Bot('YOUR_BOT_TOKEN');

  // With custom Context
  final myBot = Bot<MyContext>('YOUR_BOT_TOKEN');
}

Local Bot API

If you are hosting your own local Telegram Bot API server, you can use the Bot.local constructor.

// Initialize for local Bot API server
final bot = Bot.local(
  'YOUR_BOT_TOKEN',
  'http://localhost:8081',
);

Starting the Bot

The Bot class supports multiple ways to receive updates from Telegram.

Long Polling

The simplest way to start your bot is using Long Polling. This method actively asks Telegram for new updates. It is the default behavior when you call bot.start().

void main() async {
  final bot = Bot('YOUR_BOT_TOKEN');
  
  // Start with Long Polling (default)
  await bot.start();
}

Webhooks

Televerse has a built-in webhook server that makes it easy to run your bot on a server. The startWebhook method automatically sets up a server and registers the webhook with Telegram.

void main() async {
  final bot = Bot('YOUR_BOT_TOKEN');
  
  // Start with Webhook
  await bot.startWebhook(
    webhookUrl: 'https://your-domain.com/webhook',
    port: 3000,
  );
}

Handling Updates

Since Bot extends Composer, it provides all the methods you need to handle incoming updates. You can listen for commands, text patterns, or specific event types.

// Handle commands
bot.command('start', (ctx) => ctx.reply('Hello!'));

// Handle text patterns
bot.hears(RegExp(r'hello', caseSensitive: false), (ctx) => ctx.reply('Hi!'));

// Handle specific update types
bot.on(bot.filters.photo, (ctx) => ctx.reply('Nice photo!'));

// Handle errors
bot.onError((err) {
  print('Error: ${err.error}');
});

Under the hood, these methods register middleware that filters updates and executes your handler functions.

API Access

The Bot class exposes the raw Telegram Bot API through the api property. This allows you to call any Telegram method directly, even if it's not related to a specific update context.

// Access the RawAPI methods directly
await bot.api.sendMessage(ChatID(123456789), 'Hello directly!');

// Get bot information
print('Bot ID: ${bot.me.id}');
print('Bot Username: @${bot.me.username}');

Bot Information

Once the bot is started, you can access information about the bot itself (like its ID, name, and username) via the bot.me getter. This is equivalent to the data returned by getMe.

Stopping the Bot

To gracefully stop the bot, you can call bot.stop(). This will close the update fetcher (whether Long Polling or Webhook) and release resources.

await bot.stop();

See Also

• Context- Learn about the context object passed to handlers.
• Middleware- Understand how to use middleware in Televerse.