JTelegramBot is a Java library that wraps Telegram Bot API with a simpler API using Builder design pattern.

TelegramBot library supports full functionality of Telegram Bot API 2.1 and it consists of 3 modules:

• Core (required): This module contains the minimum required classes to use the library.
• Builders (recommended): An optional wrapper that makes Telegram Bot API much easier to use.
• Webhook (optional): An optional wrapper that enables "Webhook" mode.

Dependencies

• Java 6+
• commons-logging-1.2.jar
• jackson-annotations-2.7.2.jar
• jackson-core-2.7.2.jar
• jackson-databind-2.7.2.jar
• netty-all-4.0.34.Final.jar (only required if you use Webhook module)

Installation Instructions

• JTelegramBot-Core-v1.1.jar
• JTelegramBot-Builders-v1.1.jar
• JTelegramBot-Webhook-v1.0.jar

Other options will be added later.

How Telegram Bot works?

See https://core.telegram.org/bots/api

Usage

1. First of all, you need to create a new Telegram Bot and get an access token as described here.
2. Start writing Java code by defining an instance of the interface UpdateHandler which contains callbacks methods called upon getting new updates from Telegram server. For simplicity, you can use SimpleUpdateHandler (which provides empty implementaions) and override the callback methods you need. UpdateHandler provides the following callback methods:

• onMessageReceived(TelegramBotApi telegramBotApi, int id, Message message): Invoked on receiving new incoming message of any kind — text, photo, sticker, etc, sticker, etc.
• onInlineQueryReceived(TelegramBotApi telegramBotApi, int id, InlineQuery inlineQuery): Invoked on receiving new incoming inline query.
• onChosenInlineResultReceived(TelegramBotApi telegramBotApi, int id, ChosenInlineResult chosenInlineResult): Invoked on receiving the result of an inline query that was chosen by a user and sent to their chat partner.
• onCallbackQueryReceived(TelegramBotApi telegramBotApi, int id, CallbackQuery callbackQuery): Invoked on receiving new incoming callback query.
• onGetUpdatesFailure(Exception e): Invoked in case of an exception occurs when trying to get the new update.

3. Inside the callbck methods, wrap the low-level interface telegramBotApi with the high-level builder ApiBuilder. For example:

   @Override
   public void onMessageReceived(TelegramBotApi telegramBotApi, int id, Message message)
   {
       try
       {
           ApiBuilder.api(telegramBotApi)
                     .sendMessage("*This is a simple text message*")
                     .toChatId(message.getChat().getId())
                     .asReplyToMessage(message.getMessageId())
                     .asSilentMessage()
                     .parseMessageAs(ParseMode.MARKDOWN)
                     .execute();
       }
       catch(IOException e)
       {
           e.printStackTrace();
       }
       catch(NegativeResponseException e)
       {
           e.printStackTrace();
       }
   }
   

4. There are some builder classes that facilitates the creation of complex objects:

   • InlineKeyboardButtonBuilder builds InlineKeyboardButton[][].
   • KeyboardButtonBuilder builds KeyboardButton[][].
   • InlineQueryResultBuilder builds all of 19 types of InlineQueryResult.
   • InputMessageContentBuilder builds all of 4 types of InputMessageContent.
   • ReplyMarkupBuilder builds all of 4 types of ReplyMarkup.

5. After implmenting the interface UpdateHandler, create a new instance of JTelegramBot as follows:

   JTelegramBot bot = new JTelegramBot("BotName", API_TOKEN, updateHandler);
   

6. After that, just start the bot in Polling mode:

   bot.start(); // blocking call
   // or bot.startAsync(); non-blocking call
   

7. To start JTelegramBot in a Webhook mode, instead of starting bot directly (as in step 6), wrap it with WebhookServer:

   WebhookServer webhookServer = new WebhookServer(bot, "example.com", TelegramPort.PORT_8443, "/random/path");
   webhookServer.useGeneratedSelfSignedSslCertificate();
   webhookServer.registerWebhook();
   webhookServer.start();
   

Exceptions Handling

Most of the APIs (methods) in this library throws 2 types of exceptions:

• IOException: if an I/O exception occurs.
• NegativeResponseException: if 4xx-5xx HTTP response is received from Telegram server.

List of ApiBuilder APIs

Note: On each level of indentation, at least one method must be invoked. On the last level, execute() ends the methods chaining.

ApiBuilder.api(TelegramBotApi telegramBotApi)