multibot 1.9.3

Platform agnostic high-level bot infrastructure. Develop one bot and you will have three: one for Discord, another one for Telegram and another one for Twitch. All bots use the same objects and logic. For now there are adapters for three platforms but more may be added in the future.

Platform agnostic high-level bot infrastructure. Develop one bot and you will have three: one for Discord, another one for Telegram and another one for Twitch. All bots use the same objects and logic.

For now there are adapters for three platforms but more may be added in the future.

Installation

Python 3.10 or higher is required.

pip install multibot

Quick start

Discord

You will need create an discord application at https://discord.com/developers/applications and generate a BOT_TOKEN for your bot.

You will have to select the bot and applications.commands scopes and the Administrator permission. And as for the Discord Intents (in the Bot/Build-A-Bot panel) you must activate PRESENCE INTENT, SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT.

import os

from multibot import DiscordBot, Message

discord_bot = DiscordBot(os.environ['DISCORD_BOT_TOKEN'])


@discord_bot.register('hello')
async def function_name_1(message: Message):
    await discord_bot.send('Hi!', message)


discord_bot.start()

Telegram

You will need your own API_ID and API_HASH. To get them see Native Telegram app & MTProto configuration.

The first time you start the bot you will need a BOT_TOKEN (then you can save and reuse the session). To get your BOT_TOKEN you will need to talk to BotFather.

Other configurations with BotFather:

• Deactivate the privacy mode to read group messages or add your bot as an administrator.

• Activate the inline mode if you want to use it.

import os

from multibot import Message, TelegramBot

telegram_bot = TelegramBot(
    api_id=os.environ['TELEGRAM_API_ID'],
    api_hash=os.environ['TELEGRAM_API_HASH'],
    bot_token=os.environ['TELEGRAM_BOT_TOKEN']
)


@telegram_bot.register('hello')
async def function_name_1(message: Message):
    await telegram_bot.send('Hi!', message)


telegram_bot.start()

The session will be saved locally using SQLite.

You can save the session data in a string (string session). This serves to facilitate the use of sessions when hosting the application in cloud services with ephemeral file systems. Just change the .start() line to the following:

# telegram_bot.start()
print(telegram_bot.string_sessions)

This will print a dictionary with the bot sessions to the console:

{
    'bot_session': '................',
    'user_session': None
}

If you have a string session you can provide it instead of the bot token:

telegram_bot = TelegramBot(
    api_id=os.environ['TELEGRAM_API_ID'],
    api_hash=os.environ['TELEGRAM_API_HASH'],
    bot_session=os.environ['TELEGRAM_BOT_SESSION']  # <----- instead of bot_token
)

Adding an user bot

You can add a user bot to your telegram bot to extend certain functionalities such as accessing the message history (useful if you have not been registering the messages in a database or similar), accessing the user’s contacts to make whitelists, etc.

telegram_bot = TelegramBot(
    api_id=os.environ['TELEGRAM_API_ID'],
    api_hash=os.environ['TELEGRAM_API_HASH'],
    bot_session=os.environ['TELEGRAM_BOT_SESSION'],
    phone='+00123456789'
)

Or provide an user string session instead of phone:

telegram_bot = TelegramBot(
    api_id=os.environ['TELEGRAM_API_ID'],
    api_hash=os.environ['TELEGRAM_API_HASH'],
    bot_session=os.environ['TELEGRAM_BOT_SESSION'],
    user_session=os.environ['TELEGRAM_USER_SESSION'],
)

Twitch

You will need your own BOT_TOKEN which you can generate on: https://twitchapps.com/tmi/. For more information see https://dev.twitch.tv/docs/irc.

import os

from multibot import Message, TwitchBot

twitch_bot = TwitchBot(
    token=os.environ['TWITCH_ACCESS_TOKEN'],
    initial_channels=['channel_name'],  # Optional. You can later make the bot join a chat with join() method
    owner_name='owner_name'  # Optional. So the bot knows who to respect. Although keep in mind that the streamer cannot be punished
)


@twitch_bot.register('hello')
async def function_name_1(message: Message):
    await twitch_bot.send('Hi!', message)


twitch_bot.start()

Database (optional)

The entire library is ready to be easily configured to use your MongoDB database. It will automatically record all the information handled by the bot: messages, chats, users, etc.

To use a MongoDB database, just add environment variables:

• DATABASE_NAME (required)

• MONGO_HOST (optional. Defaults to 'localhost')

• MONGO_PORT (optional. Defaults to 27017)

• MONGO_USER (optional)

• MONGO_PASSWORD (optional)

Extended guide

How the bot works

The bot works by registering functions that will be executed later when the user provides an input message that meets the requirements specified in the arguments of Multibot.register().

Each function you have registered in the bot will receive a Message object that contains all the necessary information related to the context of said message.

Ways to design your bot

For the examples we are going to use the TelegramBot. But remember that all bots work the same since they use the same objects and logic. “They speak the same language”.

A) Simple form

import os
import random

import flanautils
from multibot import Message, TelegramBot

bot = TelegramBot(
    api_id=os.environ['TELEGRAM_API_ID'],
    api_hash=os.environ['TELEGRAM_API_HASH'],
    bot_session=os.environ['TELEGRAM_BOT_SESSION'],
    user_session=os.environ['TELEGRAM_USER_SESSION']
)


@bot.register('hello')
async def function_name_1(message: Message):
    """
    This function will be executed when someone types something like "hello".

    Functions names are irrelevant.
    """

    await bot.send('Hi!', message)  # response in same chat of received message context


@bot.register('multibot', min_score=1)
async def function_name_2(message: Message):
    """
    This function will be executed when someone types exactly "multibot".

    min_score=0.93 by default.
    """

    await bot.delete_message(message)  # deletes the received message
    bot_message = await bot.send('Message deleted.', message)  # keep the response message

    await flanautils.do_later(3, bot.delete_message, bot_message)  # delete the response message after 3 seconds


@bot.register('house home')
# @bot.register(['house', 'home'])  <-- same
# @bot.register(('house', 'home'))  <-- same
async def function_name_3(message: Message):
    """This function will be executed when someone types "house" or/and "home"."""

    await bot.clear(5, message)  # delete last 5 messages (in telegram only works if a user_bot is activated in current chat)


@bot.register([['hello', 'hi'], ['world']])  #  <-- note that is Iterable[Iterable[str]]
# @bot.register((('hello', 'hi'), ('world',)))  <-- same
# @bot.register(['hello hi', ['world']])        <-- same
# @bot.register(['hello hi', 'world'])          !!! NOT same, this is "or" logic (like previous case)
async def function_name_4(message: Message):
    """This function will be executed when someone types ("hello" or/and "hi") and "world"."""

    await bot.send('🫡', chat='user_name')


@bot.register('troll')
async def function_name_5(message: Message):
    """This function will be executed when someone types "troll" but returns if he isn't an admin."""

    if not message.author.is_admin:
        return

    await bot.ban('user_name', message)


@bot.register(always=True)
async def function_name_6(message: Message):
    """This function will be executed always but returns if bot isn't mentioned."""

    if not bot.is_bot_mentioned(message):
        return

    await bot.send('Shut up.', message)


@bot.register(default=True)
async def function_name_7(message: Message):
    """
    This function will be executed if no other function is determined by provided keywords.

    always=True functions don't affect to determine if default=True functions are called.
    """

    phrases = ["I don't understand u mate", '?', '???????']
    await bot.send(random.choice(phrases), message)


bot.start()

B) Extensible form

import os
import random

import flanautils
from multibot import Message, TelegramBot, admin, bot_mentioned


class MyBot(TelegramBot):
    def __init__(self):
        super().__init__(
            api_id=os.environ['TELEGRAM_API_ID'],
            api_hash=os.environ['TELEGRAM_API_HASH'],
            bot_session=os.environ['TELEGRAM_BOT_SESSION'],
            user_session=os.environ['TELEGRAM_USER_SESSION']
        )

    def _add_handlers(self):
        super()._add_handlers()
        self.register(self.function_name_1, 'hello')
        self.register(self.function_name_2, 'multibot', min_score=1)
        self.register(self.function_name_3, 'house home')
        self.register(self.function_name_4, [['hello', 'hi'], ['world']])  # <-- note that is Iterable[Iterable[str]]
        self.register(self.function_name_5, 'troll')
        self.register(self.function_name_6, always=True)
        self.register(self.function_name_7, default=True)

    async def function_name_1(self, message: Message):
        """
        This function will be executed when someone types something like "hello".

        Functions names are irrelevant.
        """

        await self.send('Hi!', message)  # response in same chat of received message context

    async def function_name_2(self, message: Message):
        """
        This function will be executed when someone types exactly "multibot".

        min_score=0.93 by default.
        """

        await self.delete_message(message)  # deletes the received message
        bot_message = await self.send('Message deleted.', message)  # keep the response message

        await flanautils.do_later(3, self.delete_message, bot_message)  # delete the response message after 3 seconds

    async def function_name_3(self, message: Message):
        """This function will be executed when someone types "house" or/and "home"."""

        await self.clear(5, message)  # delete last 5 messages (in telegram only works if a user_bot is activated in current chat)

    async def function_name_4(self, message: Message):
        """This function will be executed when someone types ("hello" or/and "hi") and "world"."""

        await self.send('🫡', chat='user_name')

    @admin
    async def function_name_5(self, message: Message):
        """This function will be executed when someone types "troll" but returns if he isn't an admin."""

        await self.ban('user_name', message)

    @bot_mentioned
    async def function_name_6(self, message: Message):
        """This function will be executed always but returns if bot isn't mentioned."""

        await self.send('Shut up.', message)

    async def function_name_7(self, message: Message):
        """
        This function will be executed if no other function is determined by provided keywords.

        always=True functions don't affect to determine if default=True functions are called.
        """

        phrases = ["I don't understand u mate", '?', '???????']
        await self.send(random.choice(phrases), message)


MyBot().start()

Buttons

Add buttons to the messages you send with your bot, specify a key, and register that key to a method with Multibot.register_button(). In this way, when a user presses a button associated with a key, the bot infrastructure will know which callbacks to call.

You can register multiple methods for the same key, as well as one method for multiple keys.

A) Simple form example

import os

from multibot import DiscordBot, Message

discord_bot = DiscordBot(os.environ['DISCORD_BOT_TOKEN'])


@discord_bot.register('hello')
async def function_name_1(message: Message):
    await discord_bot.send('Hi!', ['A button', 'Other button'], message, buttons_key='a_key')


@discord_bot.register_button('a_key')
async def function_name_2(message: Message):
    await discord_bot.accept_button_event(message)
    await discord_bot.send(message.buttons_info.pressed_text, message)


discord_bot.start()

B) Extensible form example

import os

from multibot import DiscordBot, Message


class MyBot(DiscordBot):
    def __init__(self):
        super().__init__(os.environ['DISCORD_BOT_TOKEN'])

    def _add_handlers(self):
        super()._add_handlers()
        self.register(self.function_name_1, 'hello')
        self.register_button(self.function_name_2, 'a_key')

    async def function_name_1(self, message: Message):
        await self.send('Hi!', ['A button', 'Other button'], message, buttons_key='a_key')

    async def function_name_2(self, message: Message):
        await self.accept_button_event(message)
        await self.send(message.buttons_info.pressed_text, message)


MyBot().start()

Run multiple bots

import asyncio
import os

from multibot import DiscordBot, Message, MultiBot, TelegramBot, TwitchBot


class MyMultiBot(MultiBot):
    def _add_handlers(self):
        super()._add_handlers()
        self.register(self.function_name_1, 'hello')

    async def function_name_1(self, message: Message):
        await self.send('Hi!', message)


class MyDiscordBot(MyMultiBot, DiscordBot):
    pass


class MyTelegramBot(MyMultiBot, TelegramBot):
    pass


class MyTwitchBot(MyMultiBot, TwitchBot):
    pass


async def main():
    discord_bot = MyDiscordBot(os.environ['DISCORD_BOT_TOKEN'])

    telegram_bot = MyTelegramBot(
        api_id=os.environ['TELEGRAM_API_ID'],
        api_hash=os.environ['TELEGRAM_API_HASH'],
        bot_token=os.environ['TELEGRAM_BOT_TOKEN']
    )

    # If you run a TwitchBot in an asyncio loop you must create it inside the loop like below.
    # Other bots like DiscordBot or TelegramBot don't have this need and can be created at the module level.
    twitch_bot = MyTwitchBot(
        token=os.environ['TWITCH_ACCESS_TOKEN'],
        initial_channels=['channel_name'],
        owner_name='owner_name'
    )

    await asyncio.gather(
        discord_bot.start(),
        telegram_bot.start(),
        twitch_bot.start()
    )


asyncio.run(main())

Annex

Native Telegram app & MTProto configuration

TelegramBot connects directly to Telegram servers using its own protocol (MTProto), so you are not limited by the http bots api. Anything you can do with the official mobile app, desktop or web is possible with this bot.

MTProto also allows the creation of user bots, bots that automate tasks with your own human account for which you would need to create a new session as when you open a session for the first time on a new device. Keep in mind that you will be asked for the security code that Telegram sends you by private chat when someone wants to log in with your account.

For both a normal bot and a user bot (bot using your “human” account) you will need the API_ID and API_HASH. To get them you will have to go to https://my.telegram.org, log in and create an app.

WARNING!

The my.telegram.org security code is NOT like a session code, do not give it to anyone, it is only to enter this website. If you have doubts: the code that MultiBot.TelegramBot may ask you for is NOT the same. MultiBot.TelegramBot would only need a different code in case of a new session when you run it for the first time.