Televerseteleverse.

Getting Started

Create your first Telegram bot with Televerse in under 5 minutes.

Prerequisites

Before we begin, make sure you have:

Creating Your First Bot

Let's create a simple bot that responds to the /start command. Create a new file called main.dart and add the following code:

main.dart
import 'package:televerse/televerse.dart';

void main() async {
  // Create a new bot instance
  final bot = Bot('YOUR_BOT_TOKEN');

  // Handle the /start command
  bot.command('start', (ctx) => ctx.reply('🚀 Welcome to Televerse!'));

  // Start listening for updates
  await bot.start();
}

Replace YOUR_BOT_TOKEN with the token you received from BotFather, then run the bot:

terminal
dart run main.dart

That's it! Your bot is now running. Open Telegram, find your bot, and send /start.

Understanding Context

Every handler receives a Context object (often named ctx). This object contains all information about the incoming update and provides convenient methods for replying:

main.dart
bot.command('profile', (ctx) async {
  // Access update information
  final user = ctx.from;
  final chatId = ctx.chat?.id;
  final messageText = ctx.text;
  
  // Reply to the user
  await ctx.reply('''
👤 User: ${user?.firstName}
🆔 Chat ID: $chatId
💬 Your message: $messageText
  ''');
});

The context provides access to:

  • ctx.message — The incoming message object
  • ctx.from — The user who sent the message
  • ctx.chat — The chat where the message was sent
  • ctx.text — The message text (shorthand)
  • ctx.api — Direct access to all Bot API methods

Handling Commands

Televerse makes it easy to handle commands. You can use bot.command()for any command, or use shortcuts like bot.settings() and bot.help():

main.dart
// Handle the /help command
bot.command('help', (ctx) async {
  await ctx.reply('''
Available commands:
/start - Start the bot
/help - Show this message
/settings - Bot settings
  ''');
});

// Handle the /settings command
bot.settings((ctx) async {
  await ctx.reply('⚙️ Settings menu coming soon!');
});

Using Filters

Televerse has a powerful filter system with 80+ built-in filters. Use bot.on() to listen for specific types of updates:

main.dart
// Listen for photo messages
bot.on(bot.filters.photo, (ctx) async {
  await ctx.reply('Nice photo! 📸');
});

// Listen for messages matching a pattern
bot.hears(RegExp(r'(?i)hello'), (ctx) async {
  await ctx.reply('Hello there! 👋');
});

// Custom filter - long messages
bot.filter(
  (ctx) => (ctx.text?.length ?? 0) > 100,
  (ctx) async {
    await ctx.reply('That was quite a long message!');
  },
);

Learn more about the filter system in the Features section.

Error Handling

Always handle errors to prevent your bot from crashing unexpectedly:

main.dart
// Global error handler
bot.onError((err) async {
  print('Error: ${err.error}');
  
  // Reply to the user if context is available
  if (err.hasContext) {
    await err.ctx!.reply('Oops! Something went wrong.');
  }
});

Next Steps

Congratulations! You've created your first Televerse bot. Here's what to explore next: