absalommj / televerse

Televerse is a Telegram Bot API Framework written completely in Dart. 💙

Televerse

🤖 Bot API version: Bot API 7.1 (February 16, 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.

🔥 Latest Update: Bot API 7.1

All the changes from the latest Bot API (7.1) are now available in Televerse. This update includes new ChatBoostAdded service message and couple of new fields in the Chat object.

Also feel free to try out the Bot API 7.0's reaction features with Televerse. Our favorite is the react method, which allows you to react to messages with emojis. For example:

  bot.start((ctx) async {
    await ctx.react("🎉");
    await ctx.reply("Happy Holidays!");
  });

Please note that there are a lot of breaking changes in this update. Please refer to the changelog for more information.

---

💻 Getting Started

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

👨🏻‍💻 Installation

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) {
  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) {
  ctx.reply('Hello, World!');
});

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

📚 Documentation

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!");

🔊 Listening for Updates

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

• bot.command to listen for commands
• bot.chatType and bot.chatTypes to listen for specific chat types
• bot.text to listen for text messages that contain specific text

There are also more advanced methods such as:

• bot.filter to create your own filters and listen for messages that match them
• bot.hear to listen for messages that match a RegExp
• bot.on to listen for specific events

These methods are very powerful and can be used to create your own custom filters.

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!');
});

Please note that we are still working on improving the documentation. In the meantime, you can refer to the example file for more information.

🦄 Even more

Televerse provides a number of helper methods to make it easy to listen for specific types of updates. For example, you can use the onURL, onHashtag, onMention, onEmail, and onPhoneNumber methods to listen for messages that contain specific types of content:

bot.onURL((ctx) {
  ctx.reply('I guess you want me to crawl this? 🕷️');
});

bot.onMention((ctx) {
  ctx.reply("Someone mentioned someone! 🤭");
});


// And so on...

You can also use the whenMentioned method to listen for messages that mention your bot:

bot.whenMentioned((ctx) {
  ctx.reply('Oh hey, I was sleeping! What did I miss?');
});

🎖️ Local Bot API Server Support

Televerse supports listening to a local Bot API Server. To use this feature, you can create a new bot instance using the local method:

/// 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",
);

This will create a bot instance that listens to updates from your local Bot API Server. You can then use the same helper methods to listen for updates, messages, and events.

🖥️ Serverless Support

You can even create bots that can run on your serverless platform such as AWS Lambda or Google Cloud Functions. On serverless platforms, you might not be able to listen for updates using a Fetcher. In this case, you can use the bot.handleUpdate method to handle updates manually.

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

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

🌟 Shoot a Star

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.

🤝 Join the Discussion

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

Thank you ❤️

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!