Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pengrad/java-telegram-bot-api
Telegram Bot API for Java
https://github.com/pengrad/java-telegram-bot-api
bot telegram telegram-api telegram-bot telegram-bot-api
Last synced: about 1 month ago
JSON representation
Telegram Bot API for Java
- Host: GitHub
- URL: https://github.com/pengrad/java-telegram-bot-api
- Owner: pengrad
- License: apache-2.0
- Created: 2015-08-04T11:58:56.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-31T17:00:05.000Z (about 2 months ago)
- Last Synced: 2024-10-31T17:26:30.859Z (about 2 months ago)
- Topics: bot, telegram, telegram-api, telegram-bot, telegram-bot-api
- Language: Java
- Homepage: https://core.telegram.org/bots
- Size: 2.44 MB
- Stars: 1,804
- Watchers: 65
- Forks: 373
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-telegram - java-telegram-bot-api - Telegram Bot API for Java. (Bots / Bot Libs)
- awesome-telegram - Java API
- awesome-telegram - Java API
README
# Java Telegram Bot API
[![Maven Central](https://img.shields.io/maven-central/v/com.github.pengrad/java-telegram-bot-api.svg)](https://search.maven.org/artifact/com.github.pengrad/java-telegram-bot-api)
[![codecov](https://codecov.io/gh/pengrad/java-telegram-bot-api/branch/master/graph/badge.svg)](https://codecov.io/gh/pengrad/java-telegram-bot-api)Java library for interacting with [Telegram Bot API](https://core.telegram.org/bots/api)
- Full support of all Bot API 7.11 methods
- Telegram [Passport](https://core.telegram.org/passport) and Decryption API
- Bot [Payments](https://core.telegram.org/bots/payments)
- [Gaming Platform](https://telegram.org/blog/games)## Download
Gradle:
```groovy
implementation 'com.github.pengrad:java-telegram-bot-api:7.11.0'
```
Maven:
```xmlcom.github.pengrad
java-telegram-bot-api
7.11.0```
[JAR with all dependencies on release page](https://github.com/pengrad/java-telegram-bot-api/releases)## Usage
```java
// Create your bot passing the token received from @BotFather
TelegramBot bot = new TelegramBot("BOT_TOKEN");// Register for updates
bot.setUpdatesListener(updates -> {
// ... process updates
// return id of last processed update or confirm them all
return UpdatesListener.CONFIRMED_UPDATES_ALL;
// Create Exception Handler
}, e -> {
if (e.response() != null) {
// got bad response from telegram
e.response().errorCode();
e.response().description();
} else {
// probably network error
e.printStackTrace();
}
});// Send messages
long chatId = update.message().chat().id();
SendResponse response = bot.execute(new SendMessage(chatId, "Hello!"));
```## Documentation
- [Creating your bot](#creating-your-bot)
- [Making requests](#making-requests)
- [Getting updates](#getting-updates)
- [Available types](#available-types)
- [Available methods](#available-methods)
- [Updating messages](#updating-messages)
- [Stickers](#stickers)
- [Inline mode](#inline-mode)
- [Payments](#payments)
- [Telegram Passport](#telegram-passport)
- [Games](#games)### Creating your bot
```java
TelegramBot bot = new TelegramBot("BOT_TOKEN");
```Network operations based on [OkHttp](https://github.com/square/okhttp) library.
You can build bot with custom OkHttpClient, for specific timeouts or interceptors.```java
TelegramBot bot = new TelegramBot.Builder("BOT_TOKEN").okHttpClient(client).build();
```### Making requests
Synchronous
```java
BaseResponse response = bot.execute(request);
```Asynchronous
```java
bot.execute(request, new Callback() {
@Override
public void onResponse(BaseRequest request, BaseResponse response) {
}
@Override
public void onFailure(BaseRequest request, IOException e) {
}
});
```Request [in response to update](https://core.telegram.org/bots/faq#how-can-i-make-requests-in-response-to-updates)
```java
String response = request.toWebhookResponse();
```### Getting updates
You can use **getUpdates** request, parse incoming **Webhook** request, or set listener to receive updates.
Update object just copies Telegram's response.```java
class Update {
Integer updateId();
Message message();
Message editedMessage();
InlineQuery inlineQuery();
ChosenInlineResult chosenInlineResult();
CallbackQuery callbackQuery();
}
```#### Get updates
Building request
```java
GetUpdates getUpdates = new GetUpdates().limit(100).offset(0).timeout(0);
```The getUpdates method returns the earliest 100 unconfirmed updates. To confirm an update, use the offset parameter when calling getUpdates like this:
`offset = updateId of last processed update + 1`
All updates with updateId less than offset will be marked as confirmed on the server and will no longer be returned.Executing
```java
// sync
GetUpdatesResponse updatesResponse = bot.execute(getUpdates);
List updates = updatesResponse.updates();
...
Message message = update.message()// async
bot.execute(getUpdates, new Callback() {
@Override
public void onResponse(GetUpdates request, GetUpdatesResponse response) {
List updates = response.updates();
}
@Override
public void onFailure(GetUpdates request, IOException e) {
}
});
```#### Webhook
Building request
```java
SetWebhook request = new SetWebhook()
.url("url")
.certificate(new byte[]{}) // byte[]
.certificate(new File("path")); // or file
```Executing
```java
// sync
BaseResponse response = bot.execute(request);
boolean ok = response.isOk();// async
bot.execute(request, new Callback() {
@Override
public void onResponse(SetWebhook request, BaseResponse response) {
}
@Override
public void onFailure(SetWebhook request, IOException e) {
}
});
```Using Webhook you can parse request to Update
```java
Update update = BotUtils.parseUpdate(stringRequest); // from String
Update update = BotUtils.parseUpdate(reader); // or from java.io.ReaderMessage message = update.message();
```#### Updates Listener
You can set a listener to receive incoming updates as if using Webhook.
This will trigger executing getUpdates requests in a loop.```java
bot.setUpdatesListener(new UpdatesListener() {
@Override
public int process(List updates) {// process updates
return UpdatesListener.CONFIRMED_UPDATES_ALL;
}
// Create Exception Handler
}, new ExceptionHandler() {
@override
public void onException(TelegramException e)
{
if (e.response() != null) {
// got bad response from telegram
e.response().errorCode();
e.response().description();
} else {
// probably network error
e .printStackTrace();
}
}
});
```Listener should return id of the last processed (confirmed) update.
To confirm all updates return `UpdatesListener.CONFIRMED_UPDATES_ALL`, this should be enough in most cases.
To not confirm any updates return `UpdatesListener.CONFIRMED_UPDATES_NONE`, these updates will be redelivered.
To set a specific update as last confirmed, just return the required updateId.To stop receiving updates
```java
bot.removeGetUpdatesListener();
```### Available types
All types have the same name as original ones.
Type's fields are methods in lowerCamelCase.Types used in responses **(Update, Message, User, Document...)** are in `com.pengrad.telegrambot.model` package.
Types used in requests **(Keyboard, InlineQueryResult, ParseMode, InputMessageContent...)** are in `com.pengrad.telegrambot.model.request` package.
When creating a request's type, required params should be passed in the constructor, optional params can be added in chains.#### Keyboards
ForceReply, ReplyKeyboardRemove
```java
Keyboard forceReply = new ForceReply(isSelective); // or just new ForceReply();
Keyboard replyKeyboardRemove = new ReplyKeyboardRemove(); // new ReplyKeyboardRemove(isSelective)
```ReplyKeyboardMarkup
```java
Keyboard replyKeyboardMarkup = new ReplyKeyboardMarkup(
new String[]{"first row button1", "first row button2"},
new String[]{"second row button1", "second row button2"})
.oneTimeKeyboard(true) // optional
.resizeKeyboard(true) // optional
.selective(true); // optional
```KeyboardButton
```java
Keyboard keyboard = new ReplyKeyboardMarkup(
new KeyboardButton[]{
new KeyboardButton("text"),
new KeyboardButton("contact").requestContact(true),
new KeyboardButton("location").requestLocation(true)
}
);
```InlineKeyboardMarkup
```java
InlineKeyboardMarkup inlineKeyboard = new InlineKeyboardMarkup(
new InlineKeyboardButton[]{
new InlineKeyboardButton("url").url("www.google.com"),
new InlineKeyboardButton("callback_data").callbackData("callback_data"),
new InlineKeyboardButton("Switch!").switchInlineQuery("switch_inline_query")
});
```#### Chat Action
```java
ChatAction action = ChatAction.typing;
ChatAction action = ChatAction.upload_photo;
ChatAction action = ChatAction.find_location;
```### Available methods
All request methods have the same names as original ones.
Required params should be passed in the constructor.
Optional params can be added in chains.#### Send message
All send requests **(SendMessage, SendPhoto, SendLocation...)** return **SendResponse** object that contains **Message**.
```java
SendMessage request = new SendMessage(chatId, "text")
.parseMode(ParseMode.HTML)
.disableWebPagePreview(true)
.disableNotification(true)
.replyToMessageId(1)
.replyMarkup(new ForceReply());// sync
SendResponse sendResponse = bot.execute(request);
boolean ok = sendResponse.isOk();
Message message = sendResponse.message();// async
bot.execute(request, new Callback() {
@Override
public void onResponse(SendMessage request, SendResponse response) {
}
@Override
public void onFailure(SendMessage request, IOException e) {
}
});
```#### Formatting options
```java
ParseMode parseMode = ParseMode.Markdown;
ParseMode parseMode = ParseMode.HTML;
```#### Get file
```java
GetFile request = new GetFile("fileId")
GetFileResponse getFileResponse = bot.execute(request);File file = getFileResponse.file(); // com.pengrad.telegrambot.model.File
file.fileId();
file.filePath(); // relative path
file.fileSize();
```
To get downloading link as `https://api.telegram.org/file//`
```java
String fullPath = bot.getFullFilePath(file); // com.pengrad.telegrambot.model.File
```#### Other requests
All requests return BaseResponse if not mention here
```java
class BaseResponse {
boolean isOk();
int errorCode();
String description();
}
```GetMe request returns GetMeResponse
```java
class GetMeResponse {
User user();
}
```GetChatAdministrators
```java
class GetChatAdministratorsResponse {
List administrators()
}
```GetChatMembersCount
```java
class GetChatMembersCountResponse {
int count()
}
```GetChatMember
```java
class GetChatMemberResponse {
ChatMember chatMember()
}
```GetChat
```java
class GetChatResponse {
Chat chat()
}
```GetUserProfilePhotos
```java
class GetUserProfilePhotosResponse {
UserProfilePhotos photos()
}
```StopPoll
```java
class PollResponse {
Poll poll()
}
```### Updating messages
Normal message
```java
EditMessageText editMessageText = new EditMessageText(chatId, messageId, "new test")
.parseMode(ParseMode.HTML)
.disableWebPagePreview(true)
.replyMarkup(new ReplyKeyboardRemove());
BaseResponse response = bot.execute(editMessageText);
```Inline message
```java
EditMessageText editInlineMessageText = new EditMessageText(inlineMessageId, "new text");
BaseResponse response = bot.execute(editInlineMessageText);
```Delete message
```java
DeleteMessage deleteMessage = new DeleteMessage(chatId, messageId);
BaseResponse response = bot.execute(deleteMessage);
```### Stickers
Send sticker
```java
// File or byte[] or string fileId of existing sticker or string URL
SendSticker sendSticker = new SendSticker(chatId, imageFile);
SendResponse response = bot.execute(sendSticker);
```Get sticker set
```java
GetStickerSet getStickerSet = new GetStickerSet(stickerSet);
GetStickerSetResponse response = bot.execute(getStickerSet);
StickerSet stickerSet = response.stickerSet();
```Upload sticker file
```java
// File or byte[] or string URL
UploadStickerFile uploadStickerFile = new UploadStickerFile(chatId, stickerFile);
GetFileResponse response = bot.execute(uploadStickerFile);
```### Inline mode
Getting updates
```java
GetUpdatesResponse updatesResponse = bot.execute(new GetUpdates());
List updates = updatesResponse.updates();
...
InlineQuery inlineQuery = update.inlineQuery();
ChosenInlineResult chosenInlineResult = update.chosenInlineResult();
CallbackQuery callbackQuery = update.callbackQuery();
```If using webhook, you can parse request to InlineQuery
```java
Update update = BotUtils.parseUpdate(stringRequest); // from String
Update update = BotUtils.parseUpdate(reader); // from java.io.ReaderInlineQuery inlineQuery = update.inlineQuery();
```#### Inline query result
```java
InlineQueryResult r1 = new InlineQueryResultPhoto("id", "photoUrl", "thumbUrl");
InlineQueryResult r2 = new InlineQueryResultArticle("id", "title", "message text").thumbUrl("url");
InlineQueryResult r3 = new InlineQueryResultGif("id", "gifUrl", "thumbUrl");
InlineQueryResult r4 = new InlineQueryResultMpeg4Gif("id", "mpeg4Url", "thumbUrl");InlineQueryResult r5 = new InlineQueryResultVideo(
"id", "videoUrl", InlineQueryResultVideo.MIME_VIDEO_MP4, "message", "thumbUrl", "video title")
.inputMessageContent(new InputLocationMessageContent(21.03f, 105.83f));
```#### Answer inline query
```java
BaseResponse response = bot.execute(new AnswerInlineQuery(inlineQuery.id(), r1, r2, r3, r4, r5));// or full
bot.execute(
new AnswerInlineQuery(inlineQuery.id(), new InlineQueryResult[]{r1, r2, r3, r4, r5})
.cacheTime(cacheTime)
.isPersonal(isPersonal)
.nextOffset("offset")
.switchPmParameter("pmParam")
.switchPmText("pmText")
);
```### Payments
Send invoice
```java
SendInvoice sendInvoice = new SendInvoice(chatId, "title", "desc", "my_payload",
"providerToken", "my_start_param", "USD", new LabeledPrice("label", 200))
.needPhoneNumber(true)
.needShippingAddress(true)
.isFlexible(true)
.replyMarkup(new InlineKeyboardMarkup(new InlineKeyboardButton[]{
new InlineKeyboardButton("just pay").pay(),
new InlineKeyboardButton("google it").url("www.google.com")
}));
SendResponse response = bot.execute(sendInvoice);
```Answer shipping query
```java
LabeledPrice[] prices = new LabeledPrice[]{
new LabeledPrice("delivery", 100),
new LabeledPrice("tips", 50)
};
AnswerShippingQuery answerShippingQuery = new AnswerShippingQuery(shippingQueryId,
new ShippingOption("1", "VNPT", prices),
new ShippingOption("2", "FREE", new LabeledPrice("free delivery", 0))
);
BaseResponse response = bot.execute(answerShippingQuery);// answer with error
AnswerShippingQuery answerShippingError = new AnswerShippingQuery(id, "Can't deliver here!");
BaseResponse response = bot.execute(answerShippingError);
```Answer pre-checkout query
```java
AnswerPreCheckoutQuery answerCheckout = new AnswerPreCheckoutQuery(preCheckoutQueryId);
BaseResponse response = bot.execute(answerPreCheckoutQuery);// answer with error
AnswerPreCheckoutQuery answerCheckout = new AnswerPreCheckoutQuery(id, "Sorry, item not available");
BaseResponse response = bot.execute(answerPreCheckoutQuery);
```### Telegram Passport
When the user confirms your request by pressing the ‘Authorize’ button, the Bot API sends an Update with the field `passport_data` to the bot that contains encrypted Telegram Passport data. [Telegram Passport Manual](https://core.telegram.org/passport#receiving-information)
#### Receiving information
You can get encrypted Passport data from Update (via UpdatesListener or Webhook)
```java
PassportData passportData = update.message().passportData();
```PassportData contains anarray of `EncryptedPassportElement` and `EncryptedCredentials`.
You need to decrypt `Credentials` using private key (public key you uploaded to `@BotFather`)```java
String privateKey = "...";
EncryptedCredentials encryptedCredentials = passportData.credentials();
Credentials credentials = encryptedCredentials.decrypt(privateKey);
```These `Credentials` can be used to decrypt encrypted data in `EncryptedPassportElement`.
```java
EncryptedPassportElement[] encryptedPassportElements = passportData.data();
for (EncryptedPassportElement element : encryptedPassportElements) {
DecryptedData decryptedData = element.decryptData(credentials);
// DecryptedData can be cast to specific type by checking instanceOf
if (decryptedData instanceof PersonalDetails) {
PersonalDetails personalDetails = (PersonalDetails) decryptedData;
}
// Or by checking type of passport element
if (element.type() == EncryptedPassportElement.Type.address) {
ResidentialAddress address = (ResidentialAddress) decryptedData;
}
}
````EncryptedPassportElement` also contains an array of `PassportFile` (file uploaded to Telegram Passport).
You need to download them 1 by 1 and decrypt content.
This library supports downloading and decryption, returns decrypted byte[]```java
EncryptedPassportElement element = ...// Combine all files
List files = new ArrayList();
files.add(element.frontSide());
files.add(element.reverseSide());
files.add(element.selfie());
if (element.files() != null) {
files.addAll(Arrays.asList(element.files()));
}
if (element.translation() != null) {
files.addAll(Arrays.asList(element.translation()));
}// Decrypt
for (PassportFile file : files) {
if (file == null) continue;
byte[] data = element.decryptFile(file, credentials, bot); // GetFile request and decrypt content
// save to file if needed
new FileOutputStream("files/" + element.type()).write(data);
}
```#### Set Passport data errors
``` java
SetPassportDataErrors setPassportDataErrors = new SetPassportDataErrors(chatId,
new PassportElementErrorDataField("personal_details", "first_name", "dataHash",
"Please enter a valid First name"),
new PassportElementErrorSelfie("driver_license", "fileHash",
"Can't see your face on photo")
);
bot.execute(setPassportDataErrors);
```### Games
Send game
```java
SendResponse response = bot.execute(new SendGame(chatId, "my_super_game"));
```Set game score
```java
BaseResponse response = bot.execute(new SetGameScore(userId, score, chatId, messageId));
```Get game high scores
```java
GetGameHighScoresResponse response = bot.execute(new GetGameHighScores(userId, chatId, messageId));
GameHighScore[] scores = response.result();
```