mirror of
https://github.com/InsanusMokrassar/TelegramBotAPI.git
synced 2024-11-22 08:13:47 +00:00
update README
This commit is contained in:
parent
51dac40e45
commit
5da60b4ac2
250
README.md
250
README.md
@ -7,244 +7,24 @@
|
|||||||
|
|
||||||
[](https://t.me/InMoTelegramBotAPI)
|
[](https://t.me/InMoTelegramBotAPI)
|
||||||
|
|
||||||
|
|
||||||
## What is it?
|
## What is it?
|
||||||
|
|
||||||
Library for Object-Oriented and type-safe work with Telegram Bot API. Most part of some specific solves or unuseful
|
It is a complex of libraries for working with `TelegramBotAPI` in type-safe and strict way as much as it possible. In
|
||||||
|
the list of this complex currently next projects:
|
||||||
|
|
||||||
|
* [TelegramBotAPI](TelegramBotAPI/README.md) - core of library. In fact it is independent library and can be used alone
|
||||||
|
without any additional library
|
||||||
|
* [TelegramBotAPI Extensions](TelegramBotAPI-extensions-api/README.md) - contains extensions (mostly for
|
||||||
|
`RequestsExecutor`), which allows to use the core library in more pleasant way
|
||||||
|
|
||||||
|
Most part of some specific solves or unuseful
|
||||||
moments are describing by official [Telegram Bot API](https://core.telegram.org/bots/api).
|
moments are describing by official [Telegram Bot API](https://core.telegram.org/bots/api).
|
||||||
|
|
||||||
## Compatibility
|
## Ok, where should I start?
|
||||||
|
|
||||||
This version compatible with [23th of January 2020 update of TelegramBotAPI (version 4.6)](https://core.telegram.org/bots/api#january-23-2020).
|
Firstly, look at the [TelegramBotAPI](TelegramBotAPI/README.md). Here you can find all information about currently
|
||||||
There is Telegram Passport API exception of implemented functionality, which was presented in
|
covered Telegram Bot API and other things. After this you can look at the
|
||||||
[August 2018 update of TelegramBotAPI](https://core.telegram.org/bots/api-changelog#august-27-2018) update. It will be implemented
|
[TelegramBotAPI Extensions](TelegramBotAPI-extensions-api/README.md).
|
||||||
as soon as possible. All APIs that are not included are presented
|
|
||||||
[wiki](https://github.com/InsanusMokrassar/TelegramBotAPI/wiki/Not-included-API).
|
|
||||||
|
|
||||||
## How to implement library?
|
Anyway, all library are very typical inside of them. For example, any request in TelegramBotAPI look like
|
||||||
|
`requestsExecutor.execute(SomeRequest())`.
|
||||||
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
|
|
||||||
`telegrambotapi.version`, which must be set up by developer. Available versions are presented on
|
|
||||||
[bintray](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI), next version is last published:
|
|
||||||
|
|
||||||
[ ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI/_latestVersion)
|
|
||||||
|
|
||||||
Currently, last versions of library can be available from the Maven repository with errors (for the reason difficult in publishing
|
|
||||||
of signed artifacts in Bintray). You can:
|
|
||||||
|
|
||||||
* Use earlier version (available version you can find
|
|
||||||
[here](https://mvnrepository.com/artifact/com.github.insanusmokrassar/TelegramBotAPI))
|
|
||||||
* Add `jCenter` repository in build config
|
|
||||||
|
|
||||||
### TelegramBotAPI
|
|
||||||
|
|
||||||
Contains core and most required things, like types, requests and `KtorRequestsExecutor`.
|
|
||||||
|
|
||||||
#### Maven
|
|
||||||
|
|
||||||
Dependency config presented here:
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<dependency>
|
|
||||||
<groupId>com.github.insanusmokrassar</groupId>
|
|
||||||
<artifactId>TelegramBotAPI</artifactId>
|
|
||||||
<version>${telegrambotapi.version}</version>
|
|
||||||
</dependency>
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Gradle
|
|
||||||
|
|
||||||
To use last versions you will need to add one line in repositories block of your `build.gradle`:
|
|
||||||
|
|
||||||
`jcenter()` or `mavenCentral()`
|
|
||||||
|
|
||||||
And add next line to your dependencies block:
|
|
||||||
|
|
||||||
```groovy
|
|
||||||
implementation "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version"
|
|
||||||
```
|
|
||||||
|
|
||||||
or for old gradle:
|
|
||||||
|
|
||||||
```groovy
|
|
||||||
compile "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version"
|
|
||||||
```
|
|
||||||
|
|
||||||
### API extensions
|
|
||||||
|
|
||||||
Contains extensions for `RequestsExecutor` which usually more obvious than original ones in `TelegramBotAPI` and more
|
|
||||||
useful.
|
|
||||||
|
|
||||||
#### Maven
|
|
||||||
|
|
||||||
Dependency config presented here:
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<dependency>
|
|
||||||
<groupId>com.github.insanusmokrassar</groupId>
|
|
||||||
<artifactId>TelegramBotAPI-extensions-api</artifactId>
|
|
||||||
<version>${telegrambotapi.version}</version>
|
|
||||||
</dependency>
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Gradle
|
|
||||||
|
|
||||||
To use last versions you will need to add one line in repositories block of your `build.gradle`:
|
|
||||||
|
|
||||||
`jcenter()` or `mavenCentral()`
|
|
||||||
|
|
||||||
And add next line to your dependencies block:
|
|
||||||
|
|
||||||
```groovy
|
|
||||||
implementation "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_version"
|
|
||||||
```
|
|
||||||
|
|
||||||
or for old gradle:
|
|
||||||
|
|
||||||
```groovy
|
|
||||||
compile "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_version"
|
|
||||||
```
|
|
||||||
|
|
||||||
## How to work with library?
|
|
||||||
|
|
||||||
For now, this library have no some API god-object. Instead of this, this library has several
|
|
||||||
important objects:
|
|
||||||
|
|
||||||
* [RequestsExecutor](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/bot/RequestsExecutor.kt)
|
|
||||||
* [Requests](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests)
|
|
||||||
* [Types](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types)
|
|
||||||
|
|
||||||
### Types
|
|
||||||
|
|
||||||
Types declare different objects representation. For example, `Chat` for now represented as
|
|
||||||
interface and has several realisations:
|
|
||||||
|
|
||||||
* `PrivateChat`
|
|
||||||
* `GroupChat`
|
|
||||||
* `SupergroupChat`
|
|
||||||
* `ChannelChat`
|
|
||||||
|
|
||||||
Instead of common garbage with all information as in original [Chat](https://core.telegram.org/bots/api#chat),
|
|
||||||
here it was separated for more obvious difference between chats types and their possible content.
|
|
||||||
|
|
||||||
The same principle work with a lot of others things in this Telegram bot API.
|
|
||||||
|
|
||||||
### Requests
|
|
||||||
|
|
||||||
Requests usually are very simple objects, but some of them are using their own
|
|
||||||
build factories. For example, the next code show, how to get information about bot:
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val requestsExecutor: RequestsExecutor = ...
|
|
||||||
requestsExecutor.execute(GetMe())
|
|
||||||
```
|
|
||||||
|
|
||||||
Or you can use new syntax (available by implementing of project [API extensions](#API-extensions):
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val bot: RequestsExecutor = ...
|
|
||||||
bot.getMe()
|
|
||||||
```
|
|
||||||
|
|
||||||
The result type of [GetMe (and getMe extension)](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/GetMe.kt)
|
|
||||||
request is
|
|
||||||
[ExtendedBot](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/User.kt).
|
|
||||||
|
|
||||||
### RequestsExecutor
|
|
||||||
|
|
||||||
It is base object which can be used to execute requests in API. For now by default included Ktor
|
|
||||||
realisation of `RequestsExecutor`, but it is possible, that in future it will be extracted in separated
|
|
||||||
project. How to create `RequestsExecutor`:
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val requestsExecutor = KtorRequestsExecutor(
|
|
||||||
TelegramAPIUrlsKeeper(TOKEN)
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
Here:
|
|
||||||
|
|
||||||
* `KtorRequestsExecutor` - default realisation with [ktor](https://ktor.io)
|
|
||||||
* `TelegramAPIUrlsKeeper` - special keeper, which you can save and use for getting files full urls (`resolveFileURL`
|
|
||||||
extension inside of `PathedFile.kt`)
|
|
||||||
* `TOKEN` is just a token of bot which was retrieved according to
|
|
||||||
[instruction](https://core.telegram.org/bots#3-how-do-i-create-a-bot).
|
|
||||||
|
|
||||||
By default, for JVM there is implemented `CIO` client engine, but there is not server engine. Both can be changed like
|
|
||||||
here:
|
|
||||||
|
|
||||||
```groovy
|
|
||||||
dependencies {
|
|
||||||
// ...
|
|
||||||
implementation "io.ktor:ktor-server-cio:$ktor_version" // for implementing of server engine
|
|
||||||
implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You can avoid using of `server` dependency in case if you will not use `Webhook`s. In this case,
|
|
||||||
dependencies list will be simplify:
|
|
||||||
|
|
||||||
```groovy
|
|
||||||
dependencies {
|
|
||||||
// ...
|
|
||||||
implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Here was used `okhttp` realisation of client, but there are several others engines for Ktor. More information
|
|
||||||
available on ktor.io site for [client](https://ktor.io/clients/http-client/engines.html) and [server](https://ktor.io/quickstart/artifacts.html)
|
|
||||||
engines.
|
|
||||||
|
|
||||||
## Getting updates
|
|
||||||
|
|
||||||
In this library currently realised two ways to get updates from telegram:
|
|
||||||
|
|
||||||
* Polling - in this case bot will request updates from time to time (you can set up delay between requests)
|
|
||||||
* Webhook via reverse proxy or something like this
|
|
||||||
|
|
||||||
### Updates filters
|
|
||||||
|
|
||||||
Currently webhook method contains `UpdatesFilter` as necessary argument for getting updates.
|
|
||||||
`UpdatesFilter` will sort updates and throw their into different callbacks. Currently supporting
|
|
||||||
separate getting updates for media groups - they are accumulating with debounce in one second
|
|
||||||
(for being sure that all objects of media group was received).
|
|
||||||
|
|
||||||
Updates polling also support `UpdatesFilter` but it is not required to use it and you can get updates directly
|
|
||||||
in `UpdateReceiver`, which you will provide to `startGettingOfUpdates` method
|
|
||||||
|
|
||||||
### Webhook set up
|
|
||||||
|
|
||||||
If you wish to use webhook method, you will need:
|
|
||||||
|
|
||||||
* White IP - your IP address or host, which available for calling. [TelegramBotAPI](https://core.telegram.org/bots/api#setwebhook)
|
|
||||||
recommend to use some unique address for each bot which you are using
|
|
||||||
* SSL certificate. Usually you can obtain the certificate using your domain provider, [Let'sEncrypt](https://letsencrypt.org/) or [create it](https://core.telegram.org/bots/self-signed)
|
|
||||||
* Nginx or something like this
|
|
||||||
|
|
||||||
Template for Nginx server config you can find in [this gist](https://gist.github.com/InsanusMokrassar/fcc6e09cebd07e46e8f0fdec234750c4#file-nginxssl-conf).
|
|
||||||
|
|
||||||
For webhook you can provide `File` with public part of certificate, `URL` where bot will be available and inner `PORT` which
|
|
||||||
will be used to start receiving of updates. Actually, you can skip passing of `File` when you have something like
|
|
||||||
nginx for proxy forwarding.
|
|
||||||
|
|
||||||
In case of using `nginx` with reverse-proxy config, setting up of Webhook will look like:
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
requestsExecutor.setWebhook(
|
|
||||||
WEBHOOK_URL,
|
|
||||||
INTERNAL_PORT,
|
|
||||||
filter,
|
|
||||||
ENGINE_FACTORY
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
Here:
|
|
||||||
|
|
||||||
* `WEBHOOK_URL` - the url which will be used by Telegram system to send updates
|
|
||||||
* `INTERNAL_PORT` - the port which will be used in bot for listening of updates
|
|
||||||
* `filter` - instance of [UpdatesFilter](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/updateshandlers/UpdatesFilter.kt),
|
|
||||||
which will be used to filter incoming updates
|
|
||||||
* `ENGINE_FACTORY` - used factory name, for example, `CIO` in case of usage `io.ktor:ktor-server-cio` as server engine
|
|
||||||
|
|||||||
75
TelegramBotAPI-extensions-api/README.md
Normal file
75
TelegramBotAPI-extensions-api/README.md
Normal file
@ -0,0 +1,75 @@
|
|||||||
|
# TelegramBotAPI
|
||||||
|
|
||||||
|
[](https://github.com/KotlinBy/awesome-kotlin)
|
||||||
|
[ ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api/_latestVersion)
|
||||||
|
[](https://maven-badges.herokuapp.com/maven-central/com.github.insanusmokrassar/TelegramBotAPI-extensions-api)
|
||||||
|
[](https://jenkins.insanusmokrassar.com/job/TelegramBotAPI-extensions-api_master__publishing/)
|
||||||
|
|
||||||
|
## What is it?
|
||||||
|
|
||||||
|
It is wrapper library for [TelegramBotAPI](../TelegramBotAPI/README.md). Here you can find extensions for
|
||||||
|
`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
|
||||||
|
|
||||||
|
This library always compatible with original `TelegramBotAPI` library version
|
||||||
|
|
||||||
|
## 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
|
||||||
|
`telegrambotapi.version`, which must be set up by developer. Available versions are presented on
|
||||||
|
[bintray](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api), next version is last published:
|
||||||
|
|
||||||
|
[ ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api/_latestVersion)
|
||||||
|
|
||||||
|
### Maven
|
||||||
|
|
||||||
|
Dependency config presented here:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>com.github.insanusmokrassar</groupId>
|
||||||
|
<artifactId>TelegramBotAPI-extensions-api</artifactId>
|
||||||
|
<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`:
|
||||||
|
|
||||||
|
`jcenter()` or `mavenCentral()`
|
||||||
|
|
||||||
|
And add next line to your dependencies block:
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
implementation "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_extensions_api_version"
|
||||||
|
```
|
||||||
|
|
||||||
|
or for old gradle:
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
compile "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_extensions_api_version"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example of usage and comparison with `TelegramBotAPI`
|
||||||
|
|
||||||
|
As said in [TelegramBotAPI](../TelegramBotAPI/README.md#Requests), it is possible to use next syntax for requests:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val requestsExecutor: RequestsExecutor = ...
|
||||||
|
requestsExecutor.execute(GetMe())
|
||||||
|
```
|
||||||
|
|
||||||
|
This library offer a little bit another way for this:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val bot: RequestsExecutor = ...
|
||||||
|
bot.getMe()
|
||||||
|
```
|
||||||
|
|
||||||
|
The result type of [GetMe (and getMe extension)](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/GetMe.kt)
|
||||||
|
request is
|
||||||
|
[ExtendedBot](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/User.kt).
|
||||||
204
TelegramBotAPI/README.md
Normal file
204
TelegramBotAPI/README.md
Normal file
@ -0,0 +1,204 @@
|
|||||||
|
# TelegramBotAPI
|
||||||
|
|
||||||
|
[](https://github.com/KotlinBy/awesome-kotlin)
|
||||||
|
[ ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI/_latestVersion)
|
||||||
|
[](https://maven-badges.herokuapp.com/maven-central/com.github.insanusmokrassar/TelegramBotAPI)
|
||||||
|
[](https://jenkins.insanusmokrassar.com/job/TelegramBotAPI_master__publishing/)
|
||||||
|
|
||||||
|
## What is it?
|
||||||
|
|
||||||
|
Library for Object-Oriented and type-safe work with Telegram Bot API. Most part of some specific solves or unuseful
|
||||||
|
moments are describing by official [Telegram Bot API](https://core.telegram.org/bots/api).
|
||||||
|
|
||||||
|
## Compatibility
|
||||||
|
|
||||||
|
This version compatible with [23th of January 2020 update of TelegramBotAPI (version 4.6)](https://core.telegram.org/bots/api#january-23-2020).
|
||||||
|
There is Telegram Passport API exception of implemented functionality, which was presented in
|
||||||
|
[August 2018 update of TelegramBotAPI](https://core.telegram.org/bots/api-changelog#august-27-2018) update. It will be implemented
|
||||||
|
as soon as possible. All APIs that are not included are presented
|
||||||
|
[wiki](https://github.com/InsanusMokrassar/TelegramBotAPI/wiki/Not-included-API).
|
||||||
|
|
||||||
|
## 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
|
||||||
|
`telegrambotapi.version`, which must be set up by developer. Available versions are presented on
|
||||||
|
[bintray](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI), next version is last published:
|
||||||
|
|
||||||
|
[ ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI/_latestVersion)
|
||||||
|
|
||||||
|
Currently, last versions of library can be available from the Maven repository with errors (for the reason difficult in publishing
|
||||||
|
of signed artifacts in Bintray). You can:
|
||||||
|
|
||||||
|
* Use earlier version (available version you can find
|
||||||
|
[here](https://mvnrepository.com/artifact/com.github.insanusmokrassar/TelegramBotAPI))
|
||||||
|
* Add `jCenter` repository in build config
|
||||||
|
|
||||||
|
### Maven
|
||||||
|
|
||||||
|
Dependency config presented here:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>com.github.insanusmokrassar</groupId>
|
||||||
|
<artifactId>TelegramBotAPI</artifactId>
|
||||||
|
<version>${telegrambotapi.version}</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gradle
|
||||||
|
|
||||||
|
To use last versions you will need to add one line in repositories block of your `build.gradle`:
|
||||||
|
|
||||||
|
`jcenter()` or `mavenCentral()`
|
||||||
|
|
||||||
|
And add next line to your dependencies block:
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
implementation "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version"
|
||||||
|
```
|
||||||
|
|
||||||
|
or for old gradle:
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
compile "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version"
|
||||||
|
```
|
||||||
|
|
||||||
|
## How to work with library?
|
||||||
|
|
||||||
|
For now, this library have no some API god-object. Instead of this, this library has several
|
||||||
|
important objects:
|
||||||
|
|
||||||
|
* [RequestsExecutor](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/bot/RequestsExecutor.kt)
|
||||||
|
* [Requests](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests)
|
||||||
|
* [Types](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types)
|
||||||
|
|
||||||
|
### Types
|
||||||
|
|
||||||
|
Types declare different objects representation. For example, `Chat` for now represented as
|
||||||
|
interface and has several realisations:
|
||||||
|
|
||||||
|
* `PrivateChat`
|
||||||
|
* `GroupChat`
|
||||||
|
* `SupergroupChat`
|
||||||
|
* `ChannelChat`
|
||||||
|
|
||||||
|
Instead of common garbage with all information as in original [Chat](https://core.telegram.org/bots/api#chat),
|
||||||
|
here it was separated for more obvious difference between chats types and their possible content.
|
||||||
|
|
||||||
|
The same principle work with a lot of others things in this Telegram bot API.
|
||||||
|
|
||||||
|
### Requests
|
||||||
|
|
||||||
|
Requests usually are very simple objects, but some of them are using their own
|
||||||
|
build factories. For example, the next code show, how to get information about bot:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val requestsExecutor: RequestsExecutor = ...
|
||||||
|
requestsExecutor.execute(GetMe())
|
||||||
|
```
|
||||||
|
|
||||||
|
Also there is an alternative syntax for requests (like `requestsExecutor.getMe()` in project
|
||||||
|
[TelegramBotAPI-extensions-api](../TelegramBotAPI-extensions-api/README.md))
|
||||||
|
|
||||||
|
The result type of [GetMe (and getMe extension)](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/GetMe.kt)
|
||||||
|
request is
|
||||||
|
[ExtendedBot](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/User.kt).
|
||||||
|
|
||||||
|
### RequestsExecutor
|
||||||
|
|
||||||
|
It is base object which can be used to execute requests in API. For now by default included Ktor
|
||||||
|
realisation of `RequestsExecutor`, but it is possible, that in future it will be extracted in separated
|
||||||
|
project. How to create `RequestsExecutor`:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val requestsExecutor = KtorRequestsExecutor(
|
||||||
|
TelegramAPIUrlsKeeper(TOKEN)
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Here:
|
||||||
|
|
||||||
|
* `KtorRequestsExecutor` - default realisation with [ktor](https://ktor.io)
|
||||||
|
* `TelegramAPIUrlsKeeper` - special keeper, which you can save and use for getting files full urls (`resolveFileURL`
|
||||||
|
extension inside of `PathedFile.kt`)
|
||||||
|
* `TOKEN` is just a token of bot which was retrieved according to
|
||||||
|
[instruction](https://core.telegram.org/bots#3-how-do-i-create-a-bot).
|
||||||
|
|
||||||
|
By default, for JVM there is implemented `CIO` client engine, but there is not server engine. Both can be changed like
|
||||||
|
here:
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
dependencies {
|
||||||
|
// ...
|
||||||
|
implementation "io.ktor:ktor-server-cio:$ktor_version" // for implementing of server engine
|
||||||
|
implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You can avoid using of `server` dependency in case if you will not use `Webhook`s. In this case,
|
||||||
|
dependencies list will be simplify:
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
dependencies {
|
||||||
|
// ...
|
||||||
|
implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Here was used `okhttp` realisation of client, but there are several others engines for Ktor. More information
|
||||||
|
available on ktor.io site for [client](https://ktor.io/clients/http-client/engines.html) and [server](https://ktor.io/quickstart/artifacts.html)
|
||||||
|
engines.
|
||||||
|
|
||||||
|
## Getting updates
|
||||||
|
|
||||||
|
In this library currently realised two ways to get updates from telegram:
|
||||||
|
|
||||||
|
* Polling - in this case bot will request updates from time to time (you can set up delay between requests)
|
||||||
|
* Webhook via reverse proxy or something like this
|
||||||
|
|
||||||
|
### Updates filters
|
||||||
|
|
||||||
|
Currently webhook method contains `UpdatesFilter` as necessary argument for getting updates.
|
||||||
|
`UpdatesFilter` will sort updates and throw their into different callbacks. Currently supporting
|
||||||
|
separate getting updates for media groups - they are accumulating with debounce in one second
|
||||||
|
(for being sure that all objects of media group was received).
|
||||||
|
|
||||||
|
Updates polling also support `UpdatesFilter` but it is not required to use it and you can get updates directly
|
||||||
|
in `UpdateReceiver`, which you will provide to `startGettingOfUpdates` method
|
||||||
|
|
||||||
|
### Webhook set up
|
||||||
|
|
||||||
|
If you wish to use webhook method, you will need:
|
||||||
|
|
||||||
|
* White IP - your IP address or host, which available for calling. [TelegramBotAPI](https://core.telegram.org/bots/api#setwebhook)
|
||||||
|
recommend to use some unique address for each bot which you are using
|
||||||
|
* SSL certificate. Usually you can obtain the certificate using your domain provider, [Let'sEncrypt](https://letsencrypt.org/) or [create it](https://core.telegram.org/bots/self-signed)
|
||||||
|
* Nginx or something like this
|
||||||
|
|
||||||
|
Template for Nginx server config you can find in [this gist](https://gist.github.com/InsanusMokrassar/fcc6e09cebd07e46e8f0fdec234750c4#file-nginxssl-conf).
|
||||||
|
|
||||||
|
For webhook you can provide `File` with public part of certificate, `URL` where bot will be available and inner `PORT` which
|
||||||
|
will be used to start receiving of updates. Actually, you can skip passing of `File` when you have something like
|
||||||
|
nginx for proxy forwarding.
|
||||||
|
|
||||||
|
In case of using `nginx` with reverse-proxy config, setting up of Webhook will look like:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
requestsExecutor.setWebhook(
|
||||||
|
WEBHOOK_URL,
|
||||||
|
INTERNAL_PORT,
|
||||||
|
filter,
|
||||||
|
ENGINE_FACTORY
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Here:
|
||||||
|
|
||||||
|
* `WEBHOOK_URL` - the url which will be used by Telegram system to send updates
|
||||||
|
* `INTERNAL_PORT` - the port which will be used in bot for listening of updates
|
||||||
|
* `filter` - instance of [UpdatesFilter](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/updateshandlers/UpdatesFilter.kt),
|
||||||
|
which will be used to filter incoming updates
|
||||||
|
* `ENGINE_FACTORY` - used factory name, for example, `CIO` in case of usage `io.ktor:ktor-server-cio` as server engine
|
||||||
Loading…
Reference in New Issue
Block a user