Package org.telegram.abilitybots.api.bot

Class BaseAbilityBot

  • All Implemented Interfaces:
    AbilityExtension
    Direct Known Subclasses:
    AbilityBot, AbilityWebhookBot
    public abstract class BaseAbilityBot
extends DefaultAbsSender
implements AbilityExtension
    The father of all ability bots. Bots that need to utilize abilities need to extend this bot.

    It's important to note that this bot strictly extends TelegramLongPollingBot.

    All bots extending the BaseAbilityBot get implicit abilities:

    • /claim - Claims this bot
    • /report - reports all user-defined commands (abilities)
      • The same format acceptable by BotFather
    • /commands - returns a list of all possible bot commands based on the privacy of the requesting user
    • /backup - returns a backup of the bot database
    • /recover - recovers the database
    • /promote @username - promotes user to bot admin
    • /demote @username - demotes bot admin to user
    • /ban @username - bans the user from accessing your bot commands and features
    • /unban @username - lifts the ban from the user

    Additional information of the implicit abilities are present in the methods that declare them.

    The two most important handles in the BaseAbilityBot are the DBContext db and the MessageSender sender. All bots extending BaseAbilityBot can use both handles in their update consumers.

    Author:
    Abbas Abou Daya

    • Method Detail

      • creatorId

        public abstract int creatorId()

      • users

        protected Map<Integer,​org.telegram.telegrambots.meta.api.objects.User> users()
        Returns:
        the map of

      • blacklist

        protected Set<Integer> blacklist()
        Returns:
        a blacklist containing all the IDs of the banned users

      • admins

        protected Set<Integer> admins()
        Returns:
        an admin set of all the IDs of bot administrators

      • abilities

        public Map<String,​Ability> abilities()
        Returns:
        the immutable map of

      • replies

        public List<Reply> replies()
        Returns:
        the immutable list carrying the embedded replies

      • onUpdateReceived

        public void onUpdateReceived​(org.telegram.telegrambots.meta.api.objects.Update update)
        This method contains the stream of actions that are applied on any update.

        It will correctly handle addition of users into the DB and the execution of abilities and replies.

        Parameters:
        update - the update received by Telegram's API

      • getBotUsername

        public String getBotUsername()

      • checkGlobalFlags

        protected boolean checkGlobalFlags​(org.telegram.telegrambots.meta.api.objects.Update update)
        Test the update against the provided global flags. The default implementation is a passthrough to all updates.

        This method should be overridden if the user wants to restrict bot usage to only certain updates.

        Parameters:
        update - a Telegram Update
        Returns:
        true if the update satisfies the global flags

      • getUser

        protected org.telegram.telegrambots.meta.api.objects.User getUser​(String username)
        Gets the user with the specified username.
        Parameters:
        username - the username of the required user
        Returns:
        the user

      • getUser

        protected org.telegram.telegrambots.meta.api.objects.User getUser​(int id)
        Gets the user with the specified ID.
        Parameters:
        id - the id of the required user
        Returns:
        the user

      • getUserIdSendError

        protected int getUserIdSendError​(String username,
                                 MessageContext ctx)
        Gets the user with the specified username. If user was not found, the bot will send a message on Telegram.
        Parameters:
        username - the username of the required user
        ctx - the message context with the originating user
        Returns:
        the id of the user

      • reportCommands

        public Ability reportCommands()

        Format of the report:

        [command1] - [description1]

        [command2] - [description2]

        ...

        Once you invoke it, the bot will send the available commands to the chat. This is a public ability so anyone can invoke it.

        Usage: /commands

        Returns:
        the ability to report commands defined by the child bot.

      • commands

        public Ability commands()
        Default format:

        PUBLIC

        [command1] - [description1]

        [command2] - [description2]

        GROUP_ADMIN

        [command1] - [description1]

        ...

        Returns:
        the ability to print commands based on the privacy of the requesting user

      • backupDB

        public Ability backupDB()
        This backup ability returns the object defined by DBContext.backup() as a message document.

        This is a high-profile ability and is restricted to the CREATOR only.

        Usage: /backup

        Returns:
        the ability to back-up the database of the bot

      • recoverDB

        public Ability recoverDB()
        Recovers the bot database using DBContext.recover(Object).

        The bot recovery process hugely depends on the implementation of the recovery method of DBContext.

        Usage: /recover

        Returns:
        the ability to recover the database of the bot

      • banUser

        public Ability banUser()
        Banned users are accumulated in the blacklist. Use DBContext.getSet(String) with name specified by BLACKLIST.

        Usage: /ban @username

        Note that admins who try to ban the creator, get banned.

        Returns:
        the ability to ban the user from any kind of bot interaction

      • unbanUser

        public Ability unbanUser()
        Usage: /unban @username
        Returns:
        the ability to unban a user

      • promoteAdmin

        public Ability promoteAdmin()
        Returns:
        the ability to promote a user to a bot admin

      • demoteAdmin

        public Ability demoteAdmin()
        Returns:
        the ability to demote an admin to a user

      • claimCreator

        public Ability claimCreator()
        Regular users and admins who try to claim the bot will get banned.
        Returns:
        the ability to claim yourself as the master and creator of the bot