pengrad/java-telegram-bot-api for Java Telegram Bots

A Typed Java Client for Telegram Bot API 10.3

This project solves the integration work required to let a Java application call the Telegram Bot API. The README identifies it as a Java library and states that it supports all Bot API 10.3 methods. It is aimed at developers building Telegram bots, especially applications that already use Java and need Telegram requests, responses, and updates represented as Java objects rather than manually parsed HTTP payloads.

The library covers several Telegram areas named in the README, including Passport and Decryption API, bot payments, and the Gaming Platform. That breadth matters because adopting a client is different from adopting the Telegram service itself. The project does not create a bot, host it, or define a bot lifecycle. It supplies Java types and an execution path for requests that the bot needs to send.

The default branch is master, and the package is published as `com.github.pengrad:java-telegram-bot-api`. The repository is not archived, and its last push was on 2026-09-26. Recent releases include 10.3.0 for Bot API 10.3, 10.1.0 for Bot API 10.1, and 10.0.0 for Bot API 10.0. Those release labels make the relationship between the library version and Telegram Bot API version visible, which is a useful adoption detail when a Telegram API version changes.

Requests, Callbacks, and OkHttp Execution

The central object is `TelegramBot`, constructed with the token received from @BotFather. Calls to Telegram are represented by request objects and executed through the bot. The README documents a synchronous form and an asynchronous form. A synchronous call returns a response directly. The asynchronous form uses a `Callback` with separate response and failure methods, and the failure parameter is an `IOException`.

This design gives the caller a choice without changing the request model. A synchronous method can be convenient for a simple command-line process or a controlled request path. The callback form is more relevant when a bot must keep processing work without blocking its calling thread. The README does not document cancellation, retry policy, or a higher-level queue, so those concerns should not be inferred from the callback API.

Network operations use OkHttp. A default bot uses the library's setup, while `TelegramBot.Builder` accepts a custom `OkHttpClient`. That extension point matters for applications that need particular timeouts or interceptors. The README does not state the default timeout values, so those values should be checked in the dependency or runtime configuration rather than guessed.

The request and response types are separated by package. Response types such as `Update`, `Message`, `User`, and `Document` are in `com.pengrad.telegrambot.model`. Request types such as `Keyboard`, `InlineQueryResult`, `ParseMode`, and `InputMessageContent` are in `com.pengrad.telegrambot.model.request`. Required parameters are passed to constructors, while optional parameters are added through chained calls. This is a conventional Java API shape, but it also means request construction can become verbose when many optional fields are needed.

Update Delivery Through getUpdates and Webhooks

Incoming updates can arrive through three documented routes: a `getUpdates` request, a webhook request parsed into an `Update`, or an updates listener that repeatedly executes `getUpdates` calls. The `Update` object copies Telegram's response and exposes fields such as `updateId()`, `message()`, `editedMessage()`, `inlineQuery()`, `chosenInlineResult()`, and `callbackQuery()`.

For polling, the README shows `GetUpdates` with a limit of 100, an offset of 0, and a timeout of 0. It explains the confirmation rule: set the offset to the update ID of the last processed update plus one. Updates with IDs below that offset are confirmed on Telegram's server and are not returned again. This makes update processing and confirmation an explicit application responsibility. If an application returns or configures the wrong offset, it can either receive updates again or skip updates that it considers confirmed.

A webhook is built with `SetWebhook`, including a URL and, optionally, a certificate from a byte array or file. The request can then be executed synchronously or asynchronously. Incoming webhook content can be parsed with `BotUtils.parseUpdate` from a string or a `java.io.Reader`. The listener offers a third option: return `UpdatesListener.CONFIRMED_UPDATES_ALL` after processing, return `UpdatesListener.CONFIRMED_UPDATES_NONE` when updates should be redelivered, or return a specific update ID. `bot.removeGetUpdatesListener()` stops the listener.

These routes are not interchangeable. The listener repeatedly executes `getUpdates` requests in a loop. A webhook uses a URL and can be configured with certificate bytes or a file. The README does not document webhook retries, endpoint authentication, or deployment guidance, so those parts belong in the surrounding application and hosting setup.

Gradle and Maven Installation with a First Send

The README gives a Maven-compatible dependency declaration and a Gradle dependency line for version 10.3.0. Add the dependency to the Java build, then create a bot with the token received from @BotFather and register an update listener. The following is the documented first-use shape.

TelegramBot bot = new TelegramBot("BOT_TOKEN");

The listener receives updates, processes them, and returns `UpdatesListener.CONFIRMED_UPDATES_ALL`. Its exception handler distinguishes a Telegram response error from a network error, as shown below.

bot.setUpdatesListener(updates -> {
    return UpdatesListener.CONFIRMED_UPDATES_ALL;
}, e -> {
    if (e.response() != null) {
        e.response().errorCode();
        e.response().description();
    } else {
        e.printStackTrace();
    }
});

A first message can be sent after an update supplies a chat ID. The documented request is:

long chatId = update.message().chat().id();
SendResponse response = bot.execute(new SendMessage(chatId, "Hello!"));

For a custom network client, the README documents this builder form:

TelegramBot bot = new TelegramBot.Builder("BOT_TOKEN").okHttpClient(client).build();

The dependency version should be selected deliberately because the README says that 10.3.0 supports Bot API 10.3. The repository also links to release-page JAR files that include dependencies, but it does not explain when the bundled JAR is preferable to normal dependency management.

Where the Library Ends and the Application Begins

The clearest limitation is scope. java-telegram-bot-api is a client library, not a complete bot application framework. The README shows request execution, update parsing, and type mapping, but it does not document state storage, command routing, scheduled jobs, user session management, deployment, observability, or a ready-made message handler. An application still needs to decide what to do after receiving a message and how to report failures.

Update confirmation is the most concrete operational constraint. Polling returns unconfirmed updates, and confirmation depends on the offset or the listener's return value. An application must define when an update counts as processed. Returning `CONFIRMED_UPDATES_ALL` is described as sufficient in many cases, but that does not remove the need for correct processing boundaries. Returning `CONFIRMED_UPDATES_NONE` causes redelivery, which can be useful during development but can also create repeated work if the confirmation policy is not managed.

The library also leaves transport configuration open. It uses OkHttp, and custom clients are supported, but the README does not specify retry behavior, rate-limit handling, proxy configuration, shutdown lifecycle, or persistence. Those omissions mean adoption requires checking the relevant Telegram API and OkHttp behavior rather than assuming the library supplies it.

A real alternative is to call Telegram's HTTP endpoints from a general-purpose HTTP client and map JSON yourself. That approach offers fewer library-specific abstractions and can fit a codebase that already has HTTP, serialization, retry, and observability conventions. java-telegram-bot-api is the better fit when the team wants Telegram-specific request classes, response types, and update helpers without implementing that mapping layer first.

Maintenance, Licensing, and Version Tracking

The repository is not archived, and the last push was on 2026-09-26. The release list shows 10.3.0 on 2026-09-26, 10.1.0 on 2026-06-12, and 10.0.0 on 2026-05-29. The project therefore has recent documented release activity in the repository record. The maintenance signal available here is the push date and release history; the README does not describe a support policy, issue response time, or long-term-support branch.

The project uses the Apache-2.0 license. That identifies the license declared by the repository, but it is not legal advice about how a particular application must use the library. Teams should review the repository's LICENSE file and their own distribution requirements when packaging the dependency.

Upgrading requires attention to both sides of the version relationship. The release names pair library versions with Telegram Bot API versions, so an upgrade may add or change methods and model fields as Telegram changes. The README states full support for Bot API 10.3 methods in the current release, but it does not provide a migration guide or compatibility matrix. Before changing versions, compare the selected library release with the Bot API behavior required by the bot, then compile and exercise the request and response types used by the application.

Editorial conclusion

Adopt java-telegram-bot-api when the application is written in Java and needs a typed client for Telegram Bot API 10.3, especially when synchronous, asynchronous, polling, or webhook access fits the deployment. Do not choose it as a framework for bot orchestration, persistence, or deployment, because the repository documents a client library rather than those services. Verify first that your bot token handling, update-confirmation policy, custom OkHttpClient settings, and chosen polling or webhook model match the application's requirements. The latest documented release is 10.3.0, corresponding to Bot API 10.3, and the repository's last push was on 2026-09-26.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pengrad/java-telegram-bot-api on GitHub
3. Project website
4. README
5. Releases