1
0
mirror of https://github.com/InsanusMokrassar/TelegramBotAPI.git synced 2024-11-25 03:28:44 +00:00
tgbotapi/tgbotapi.api/README.md

128 lines
3.8 KiB
Markdown
Raw Normal View History

2021-10-18 09:37:10 +00:00
# TelegramBotAPI API extensions
2020-02-17 09:25:08 +00:00
2021-10-18 09:37:10 +00:00
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.api)
2021-08-22 04:58:32 +00:00
2020-02-17 09:25:08 +00:00
## What is it?
2020-10-04 12:54:57 +00:00
It is wrapper library for [TelegramBotAPI Core](../tgbotapi.core/README.md). Here you can find extensions for
2020-02-17 09:25:08 +00:00
`RequestsExecutor`, which are more look like Telegram Bot API requests and in the same time have more obvious signatures
to help understand some restrictions in Telegram system.
## Compatibility
2020-10-04 12:34:03 +00:00
This library always compatible with original `tgbotapi.core` library version
2020-02-17 09:25:08 +00:00
## How to implement library?
Common ways to implement this library are presented here. In some cases it will require additional steps
like inserting of additional libraries (like `kotlin stdlib`). In the examples will be used variable
2021-10-18 09:37:10 +00:00
`telegrambotapi-extensions-api.version`, which must be set up by developer.
2020-02-17 09:25:08 +00:00
2021-10-18 09:37:10 +00:00
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.api)
2020-02-17 09:25:08 +00:00
### Maven
Dependency config presented here:
```xml
<dependency>
2020-10-04 11:41:30 +00:00
<groupId>dev.inmo</groupId>
2021-10-18 09:37:10 +00:00
<artifactId>tgbotapi.api</artifactId>
2020-02-17 09:25:08 +00:00
<version>${telegrambotapi-extensions-api.version}</version>
</dependency>
```
### Gradle
To use last versions you will need to add one line in repositories block of your `build.gradle`:
2021-10-13 08:22:01 +00:00
`mavenCentral()`
2020-02-17 09:25:08 +00:00
And add next line to your dependencies block:
```groovy
2021-10-18 09:37:10 +00:00
implementation "dev.inmo:tgbotapi.api:$telegrambotapi_extensions_api_version"
2020-02-17 09:25:08 +00:00
```
or for old gradle:
```groovy
2021-10-18 09:37:10 +00:00
compile "dev.inmo:tgbotapi.api:$telegrambotapi_extensions_api_version"
2020-02-17 09:25:08 +00:00
```
## Example of usage and comparison with `TelegramBotAPI`
2020-03-31 05:11:37 +00:00
Here presented review table for comparison of api from original [TelegramBotAPI](../TelegramBotAPI/README.md#Requests)
2020-05-12 12:52:37 +00:00
and extensions-api library. First of all, this library allow to create bot instance in a new way:
2020-03-31 05:11:37 +00:00
2020-05-12 12:52:37 +00:00
```kotlin
val bot = telegramBot("IT IS YOUR TOKEN")
```
There are a lot of signature for this. For example, you can create bot with next code:
2020-02-17 09:25:08 +00:00
```kotlin
2020-05-12 12:52:37 +00:00
val bot = telegramBot("IT IS YOUR TOKEN") {
proxy = ProxyBuilder.socks("127.0.0.1", 1080)
}
2020-03-31 05:11:37 +00:00
```
2020-02-17 09:25:08 +00:00
2020-05-12 12:52:37 +00:00
In all examples supposed that you have created bot.
2021-10-18 09:37:10 +00:00
| tgbotapi.core | tgbotapi.api |
2020-08-20 05:55:39 +00:00
|---------------------|-------------------------------|
2020-03-31 05:11:37 +00:00
| bot.execute(GetMe) | bot.getMe() |
| bot.execute(SendTextMessage(someChatId, text)) | bot.sendTextMessage(chat, text) |
## Updates
2020-05-14 18:48:34 +00:00
**Currently, these paragraphs almost outdated due to the fact that extensions for listening of updates and webhooks were
2021-10-18 09:37:10 +00:00
replaced into `tgbotapi.utils`. But, most part of information below is correct with small fixes and
adding of `tgbotapi.utils` dependency.**
2020-05-14 18:48:34 +00:00
2020-03-31 05:11:37 +00:00
Usually, it is more comfortable to use filter object to get separated types of updates:
2020-02-17 09:25:08 +00:00
```kotlin
2020-03-31 05:11:37 +00:00
val filter = FlowsUpdatesFilter(100)
2020-02-17 09:25:08 +00:00
```
2020-03-31 05:11:37 +00:00
In this case you will be able:
* Separate types of incoming updates (even media groups)
* Simplify launch of getting updates:
```kotlin
bot.startGettingOfUpdates(
filter,
scope = CoroutineScope(Dispatchers.Default)
)
```
* Use `filter` flows to comfortable filter, map and do other operations with the whole
getting updates process:
```kotlin
filter.messageFlow.mapNotNull {
it.data as? ContentMessage<*>
}.onEach {
println(it)
}.launchIn(
CoroutineScope(Dispatchers.Default)
)
```
2020-04-08 08:02:55 +00:00
### Alternative way
There is an alternative way to get updates. In fact it is almost the same, but could be more useful for some cases:
```kotlin
val filter = bot.startGettingOfUpdates(
scope = CoroutineScope(Dispatchers.Default)
) { // Here as reveiver will be FlowsUpdatesFilter
messageFlow.mapNotNull {
it.data as? ContentMessage<*>
}.onEach {
println(it)
}.launchIn(
CoroutineScope(Dispatchers.Default)
)
}
```