Home

Welcome to the jTelegram wiki!

Here you'll find the utilities to both use and add to jTelegram. From this wiki, you'll be able to learn the patterns of this API that will allow you to use it seamlessly, only occasionally having to refer to the Telegram Documentation.

Getting Started

Maven

You can add this API as a dependency using Maven.

<dependencies>
    <dependency>
        <groupId>com.jtelegram</groupId>
        <artifactId>jtelegrambotapi-core</artifactId>
        <version>4.0.1</version>
    </dependency>
</dependencies>

Starting the Registry

At first, we have a bot registry. TelegramBotRegistry is the manager for all created bots under it. We will need to start by selecting our update method. For the sake of simplicity, we will be using Polling, however feel free to refer to our Webhooks vs. Polling page for more information to make your decision.

Now, let's start writing code! In this project, builders are everywhere, and of course, we will start by using one here.

TelegramBotRegistry registry = TelegramBotRegistry.builder()
        // simple
        .updateProvider(new PollingUpdateProvider())
        // complex
        .updateProvider(
                PollingUpdateProvider.builder()
                        .timeout(100)
                        .allowedUpdate(UpdateType.MESSAGE)
                        .allowedUpdate(UpdateType.INLINE_QUERY)
                        .build()
        )
        .build();

For more information on how you can customize polling, refer to here.

Registering a Bot

Now that you're done, it's time to register your bot. You can do that like so

registry.registerBot("<your api key>", (bot, error) -> {
    if (error != null) {
        // we failed to login :(
        return;
    }

    // yay we logged in, now interact with your TelegramBot object!
});

Running this method will verify your api key to work, and remove any webhooks setup previously (even ones on other runtimes). This is done to allow polling to function properly, or to replace the old one by the currently running webhook.

Note that you can add as many bots as you want to the registry. At the moment, there is no easy way to remove your bot from the registry.

Listening for Events

When a user sends you a message, or a user is removed from a group, you want your bot to be able to easily react to these events and act accordingly. This is extremely easy with jTelegram, you can do it like so:

bot.getEventRegistry().registerEvent(TextMessageEvent.class, (event) -> {
    TextMessage message = event.getMessage();
    System.out.println(message.getContent() + " received from " + message.getSender().getFullName());
});

All the events that can be listened for can be found under the org.jtelegram.api.event package -- they vary from message event, to chat actions (new title, new photo, etc.), to payments.

Sending Requests

Requests are extremely simple, more often than not they will almost identically match the endpoints in the API but in upper camel case form. They can be sent using the TelegramBot method:

bot.perform(SendText.builder()
      .chatId(ChatId.from("@PavelDurov"))
      .text("Telegram is awesome!")
      .build()
)

Now, you may have noticed, the perform method returns void, so how do I handle responses and more importantly... exceptions.

Telegram is notorious for not having implemented errors well. It's not standardized at all, and even @BotSupport admitted that this has been a long desired feature yet to be implemented. Due to this, many API wrappers are well known for not having close-to-no exception support.

Regardless, jTelegram offers exception handling for network and Telegram errors. At the moment, detailed exception types from the description parameter are a work in progress; however, you can take comfort in the fact that your bot will be able to inform users of errors and appropriately handle them.

For all requests, you can handle errors by providing a Consumer<TelegramError> as the errorHandler as in the example below.

For requests which return basic values such as true or none at all, you can handle success by providing a Runnable as the callback.

For requests which return proper responses, a Consumer<T> of the response type will be sufficient as the callback.

bot.perform(SendText.builder()
      .chatId(ChatId.from("@PavelDurov"))
      .text("Telegram is awesome!")
      .callback((message) -> {
          System.out.println("Message successfully sent with id " + message.getMessageId())
      })
      .errorHandler((ex) -> {
          if (ex instanceof NetworkException) {
              System.out.println("Something is wrong with the network... Check network connection and try again");
              ((NetworkException) ex).getUnderlyingException().printStackTrace();
              return;
          }

          System.out.println("Telegram returned an error (" + ex.getErrorCode() + "," + ex.getDescription() + ")");
      })
      .build()
);