Televerse

🤖 Bot API version: Bot API 7.6 (July 1, 2024)

Televerse is a powerful, easy-to-use, and highly customizable Telegram bot framework built with Dart programming language. It provides a complete and well-structured API that enables developers to create and deploy complex Telegram bots with ease. Televerse provides a total of 0 dynamic types on its public interface, making it easy for developers to write strictly typed code.

(🗓️ July 1, 2024)

In a nutshell, the updates include support for the new Paid Media messages. Brings the new sendPaidMedia message to send paid media messages. Introduces TransactionPartnerTelegramAds, new field in ChatFullInfo, and more.

Checkout changelog for more details! 🚀

(🗓️ June 28, 2024)

Televerse now lets you build even more powerful bots with custom contexts!

• Design custom context classes to store information specific to your bot's needs.
• Keep your bot's logic organized with private context members and methods.
• Add features like localization by integrating mixins.

With the new Bot.contextBuilder method, you can define specialized context constructors to create context objects with personalized behaviors and capabilities. This update allows you to tailor your bot's responses, handle complex workflows, and integrate additional features seamlessly.

(🗓️ June 22, 2024)

You can now use the Bot.use method to attach middlewares to your bot. These middlewares will be processed before your main handler runs, allowing you to pre-process or even decide whether to execute the main handler. Additionally, using a Transformer lets you directly modify the request payload, reducing redundant code and simplifying your coding experience.

Creating a bot with Televerse is very easy! First, you need to import the Televerse package:

Add this to your package's pubspec.yaml file:

dependencies:
  televerse: <latest>

Now in your Dart code, you can import the Televerse package:

import 'package:televerse/televerse.dart';

After importing the package, you can create a new bot instance by providing your bot token:

Bot bot = Bot('YOUR_BOT_TOKEN');

Now, you can start listening for updates such as messages, commands, etc. To start polling updates from Telegram servers, simply call:

bot.start();

That's it! Your bot is now ready to receive updates from Telegram.

If you want to handle a specific command, such as the /start command, you can use the bot.command method. For example:

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

Starting from Televerse 1.3.1, you can use the bot.start method to start listening for updates and also set up a command listener for the /start command. That means you can simplify the code above like this:

bot.start((ctx) async {
  await ctx.reply('Hello, World!');
});

And that's all you need to get started with Televerse!

Televerse has a new API that is much simpler and easier to use. You can now use the bot instance to access the powerful Televerse methods and properties, and if you want to access the Telegram Bot API methods, you can use the bot.api getter. Simple, and clean.

Now, when you're inside a callback function, you can use the Context parameter which also provides you with the api property.

For example, if you want to send a message to a specific chat you can do it like this:

bot.api.sendMessage(ChatID(123456), "Hello, World!");

// or with the context

ctx.api.sendMessage(ChatID(123456), "Hello, World!");

Televerse also offers a set of custom methods to simplify your development process. Some of these methods include:

• bot.command to listen for commands

Let's see an example:

bot.command("hello", (ctx) async {
  await ctx.reply("Hello World 👋");
  // ...
});

Similarly, you have access to many listener methods including bot.hear, bot.on, bot.callbackQuery etc to listen to specific events.

Televerse also let's you create your own filter to cherrypick the specific update and process it.

For example, if you want to listen for messages that contain a photo with a size greater than 1MB, you can do it like this:

bot.filter((ctx) {
  return (ctx.message.photo?.last.fileSize ?? 0) > 1000000;
}, (ctx) {
  ctx.reply('Wow, that\'s a big photo!');
});

More listener methods listed in the features section.

Televerse uses 0 dynamic types on the public interface, ensuring type safety and reliability throughout your bot development process.

Host your own Bot API server and listen to updates effortlessly with Televerse. Simply use the Bot.local constructor to configure your bot with a custom base URL.

/// Creates the bot instance, optionally passing the base URL of the local Bot API Server.
final Bot bot = Bot.local(
 "YOUR_BOT_TOKEN",
 baseURL: "mybotapi.com",
);

Whether you're using Cloud Functions or Lambda Functions, Televerse has you covered. Utilize Bot.handleUpdate to handle updates manually in your serverless environment.

// Create bot instance, and setup listeners
// ...

final json = jsonDecode(event.body);
final update = Update.fromJson(json);
bot.handleUpdate(update);

Say goodbye to uncertainty with Televerse's LoggerOptions, allowing you to customize network logging options to your heart's content.

final bot = Bot(
 "YOUR_BOT_TOKEN",
 loggerOptions: LoggerOptions(
   requestBody: true,
   requestHeader: true,
   responseBody: true,
   methods: [
     APIMethod.sendMessage,
     APIMethod.sendPhoto,
   ],
 ),
);

Easily create Keyboard Reply Markup and Inline Keyboard Markup with Televerse's intuitive utility classes. Easy as it sounds.

bot.start((ctx) async {
  final keyboard = Keyboard()
    .text("Account")
    .text("Referral")
    .row()
    .text("Settings")
    .resized();

  await ctx.reply(
    "Choose an option:",
    replyMarkup: keyboard,
  );
});

Televerse offers a wide array of listener methods to cater to your bot's needs, including:

• And much much more :)

Wait a second, did we miss your use case? Create your own listener methods with ease using Bot.filter.

bot.filter((ctx) {
  return (ctx.message.photo?.last.fileSize ?? 0) > 1000000;
}, (ctx) async {
  ctx.reply('Wow, that\'s a big photo!');
});

Stay up-to-date with the latest version of the Telegram Bot API, supported by Televerse. That's a promise.

Handle errors gracefully with Bot.onError, catching almost all uncaught errors from any handlers.

import 'dart:developer';

// ...

bot.onError((err) {
  log(
    "Something went wrong: $err",
    error: err.error,
    stackTrace: err.stackTrace,
  );
});

Engage users in one-on-one conversations with the Conversation API, waiting for their messages seamlessly.

// Create your bot instance
final bot = Bot(
  "YOUR_BOT_TOKEN",
);

// Create the Conversation API instance
final conv = Conversation(bot);

bot.start((ctx) async {
  await ctx.reply("Hello, I am ${ctx.me.firstName}. What should I call you?");

  // Now wait you can wait for the user's reply message. Easy, right?
  final nameCtx = await conv.waitForTextMessage(chatId: ctx.id);
  await nameCtx?.reply("Good to meet you, ${ctx.message?.text}");
});

Effortlessly build Inline Reply Markup and Keyboard Reply Markup with Televerse's utility classes, bound with handler methods for button taps.

// Define handler methods
Future<void> accountHandler(Context ctx) async {
  await ctx.replyWithPhoto(InputFile.fromFile(File("hello.png")));
  await ctx.reply("Here's your account details...");
}

// Define menu options
final menu = KeyboardMenu()
  .text("Account", accountHandler)
  .text("Referral", referralHandler)
  .text("Settings", settingsHandler)
  .resized();

// Attach menu to bot
bot.attachMenu(menu);

// Start bot
bot.start((ctx) async {
  await ctx.reply(
    "Hello, I am ${ctx.me.firstName}. Let's start.",
    replyMarkup: menu,
  );
});

Efficiently build inline query results with the InlineQueryResultBuilder, simplifying the process of generating inline query results.

Televerse support Middlewares and Transformers in the library. These features allow you to preprocess and manipulate API requests seamlessly.

Middlewares let you execute code before your main handler is run. This is useful for tasks like logging, authentication, and more.

class LoggingMiddleware implements Middleware {
  @override
  Future<void> handle(
    Context ctx,
    NextFunction next,
  ) async {
    print('Received update: ${ctx.update}');
    await next();
  }
}

// Usage
bot.use(LoggingMiddleware());

Transformers allow you to alter the request payloads directly, providing a more flexible way to modify requests before they are sent to the API.

class AutoReplyEnforcer implements Transformer {
  @override
  Future<Map<String, dynamic>> transform(
    APICaller call,
    APIMethod method,
    Payload payload,
  ) async {
    final isSendMethod = APIMethod.sendMethods.contains(method);
    final isNotChatAction = method != APIMethod.sendChatAction;

    if (isSendMethod && isNotChatAction) {
      payload.params["reply_markup"] = ForceReply().toJson();
    }

    return await call(method, payload);
  }
}


// Usage
bot.use(AutoReplyEnforcer());

If you find Televerse helpful, please consider shooting a star on our Github repository. This helps us to know that our work is appreciated and motivates us to continue improving Televerse.

We have an active Telegram group where you can discuss Televerse and get help from other users and developers.

Televerse is a powerful and easy-to-use library for building Telegram bots in Dart. With its fully typed interface and helpful helper methods, you can write clean, maintainable code that responds to messages and updates on Telegram. So, what are you waiting for? Start building your Telegram bot with Televerse today!