Simple Telegram Command Bot Spring Boot Starter

A simple-to-use library to create Telegram Bots in Java and Spring Boot with syntax like Spring MVC

• Simple Telegram Command Bot Spring Boot Starter
  • Usage
  • How to use
  • BotRoute
  • CommandMapping
  • CommandDescription
  • Authorization
  • Supported arguments
    • Arguments by type
    • Arguments by annotation
  • Supported return values
    • Single value
    • Collection value
    • Reactive support
  • Default Commands
  • Logging Channel
  • Handle Exception
    • BotRouteAdvice
    • BotExceptionHandler
    • Supported return values of BotExceptionHandler
  • CallbackQuerySubscriber
  • Others Subscriber Bean
  • Configurations
    • Properties
  • JavaDocs

Table of contents generated with markdown-toc

Usage

Just import add the library to your project with one of these options:

Using Maven Central Repository:

• Step 1. Add the JitPack repository to your build file

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

• Step 2. Add the dependency

<dependency>
    <groupId>com.github.ndanhkhoi</groupId>
    <artifactId>simple-telegram-command-bot-spring-boot-starter</artifactId>
    <version>2023.08.21</version>
</dependency>

Using Gradle:

• Step 1. Add the JitPack repository to your build file

repositories {
    maven { url 'https://jitpack.io' }
}

• Step 2. Add the dependency

dependencies {
    implementation 'com.github.ndanhkhoi:simple-telegram-command-bot-spring-boot-starter:2023.08.21'
}

How to use

• Create spring boot application from Spring Initializr

• Add Telegram Bot Java Library as dependency

• Add Simple Telegram Command Bot Spring Boot Starter

• Add bot's properties to your application.yml

khoinda:
  bot:
    username: { YOUR_BOT_USERNAME }
    token: { YOUR_BOT_TOKEN }
    bot-route-packages:
      - { YOUR_BOT_ROUTES_PACKAGE }

• Create your bot route

@BotRoute
public class HelloWorldBotRoute {

    @CommandDescription("Say hello world")
    @CommandMapping(value = "/hi", allowAllUserAccess = true)
    public String hi(Update update) {
        return "Hello world";
    }

}

BotRoute

An annotation indicates that a particular class serves the role of a router.

CommandMapping

An annotation is used to map bot requests to route methods.

CommandDescription

An annotation is used to describe command. You can see it which default /help command

Authorization

You can authorize command with these properties in @CommandMapping annotaion:

• allowAllUserAccess - boolean, if true all users/group can be call this command
• allowAllGroupAccess - a flag to mark a command can be called by any groups
• accessUserIds - an array contains user id can call this command
• accessGroupIds - an array contains group id can call this command
• accessMemberIds - an array contains user id can call this command in the group
• onlyAdmin - boolean, if true only admin of group can be call this command
• onlyForGroup - boolean, a flag to mark a command can be called in groups
• onlyForOwner - boolean, if true only bot's owner can be call this command

Supported arguments

Arguments by type

• Update - An Update object of telegram bot API
• Message - A message object of telegram bot API
• List<PhotoSize> - If message contains photo, it will be hold them, or else it will be return null
• Document - If message contains file, it will be hold them, or else it will be return null

Arguments by annotation

• @CommandName - An annotation to mark a param in command method as a command name
• @CommandBody - An annotation to mark a param in command method as a command body
• @ChatId - An annotation to mark a param in command method as a chat id, can be used on Long type
• @SendUserId - An annotation to mark a param in command method as a user id, can be used on Long type
• @SendUsername - An annotation to mark a param in command method as a username, can be used on String type

Supported return values

Single value

• String/Number - the text will be reply to user make a request
• InputFile/File/byte[]/ByteArrayResource - the file will be reply to user make a request
• BotApiMethod - it will be excuted automatically
• Void - do nothing

Collection value

• Collection<T> - with T is one of single value types, it will be do a same job with single value types for each element in this collection

Reactive support

• Mono<T> - same as single value but for Reactive
• Flux<T> - same as collection value but for Reactive

Default Commands

• /help - List of available command(s) for this chat
• /get_log_file - Get an application log file. This command must be called by owner of a bot in khoinda.bot.bot-owner-chat-id in application.properties or application.yml

Logging Channel

If you want to send log when new update received, you can config your channel id to khoinda.bot.logging-chat-id in application.properties or application.yml

Handle Exception

Here is an example for handler of NoSuchElementException. When bot command request throw NoSuchElementException, it will reply a text: "404 Not Found !"

@BotRouteAdvice
public class RouteAdvice {

    @BotExceptionHandler(NoSuchElementException.class)
    public String handleNoSuchElement(Update update, NoSuchElementException ex) {
        return "404 Not Found !";
    }

}

BotRouteAdvice

An annotation indicates that a particular class serves the role of a router for exception.

BotExceptionHandler

An annotation is used to mark method is a exception handler.

Supported return values of BotExceptionHandler

• String - the text will be replied to user make a request
• BotApiMethod - it will be excuted automatically

CallbackQuerySubscriber

You can create a bean that inplements CallbackQuerySubscriber to trigger callback query:

@Component
public class CustomCallbackQuerySubscriber implements CallbackQuerySubscriber {

    @Override
    public void accept(Update update) throws Exception {
        SendMessage sendMessage = new SendMessage();
        sendMessage.setText("Callback query data: " + update.getCallbackQuery().getData());
        sendMessage.setChatId(update.getCallbackQuery().getMessage().getChatId() + "");
        BotDispatcher.getInstance().getSender().execute(sendMessage);
    }

}

Others Subscriber Bean

There are some beans that you can create an inplements to do your stuff

• CallbackQuerySubscriber - handle callback query (like button pressed, etc, ...)
• CommandNotFoundUpdateSubscriber - handle unknown commands
• NonCommandUpdateSubscriber - handle an update does not contain command
• PreSubscriber - do your job before process command
• PosSubscriber - do your job after process command
• AfterRegisterBotSubscriber - do your job after register bot

Configurations

Properties

By default, you can configure only these properties:

Property	Description	Default value
khoinda.bot.enable-auto-config	Enable bot auto configuration	true
khoinda.bot.username	Bot's username
khoinda.bot.token	Bot's token
khoinda.bot.logging-chat-id	Chat id can received logging when new Update recieved
khoinda.bot.bot-owner-chat-id	Chat id of bot's owner	new ArrayList<>()
khoinda.bot.bot-route-packages	Package(s) name that includes BotRoute class	new ArrayList<>()
khoinda.bot.enable-update-trace	Enable /update_trace for owner	false
khoinda.bot.disable-default-commands	Disable /help, /start by default	false
khoinda.bot.show-command-menu	Show command on bot