update readmes with updates handling
This commit is contained in:
parent
dc173d752c
commit
095c91bf39
|
|
@ -78,6 +78,10 @@ In all examples supposed that you have created bot.
|
|||
|
||||
## Updates
|
||||
|
||||
**Currently, these paragraphs almost outdated due to the fact that extensions for listening of updates and webhooks were
|
||||
replaced into `TelegramBotAPI-extensions-utils`. But, most part of information below is correct with small fixes and
|
||||
adding of `TelegramBotAPI-extensions-utils` dependency.**
|
||||
|
||||
Usually, it is more comfortable to use filter object to get separated types of updates:
|
||||
|
||||
```kotlin
|
||||
|
|
|
|||
|
|
@ -60,13 +60,80 @@ val filter = FlowsUpdatesFilter(64)
|
|||
Alternative way to use the things below:
|
||||
|
||||
```kotlin
|
||||
val filter = bot.startGettingUpdates(
|
||||
val filter = bot.startGettingFlowsUpdatesByLongPolling(
|
||||
scope = CoroutineScope(Dispatchers.Default)
|
||||
) {
|
||||
// place code from examples here with replacing of `filter` by `this`
|
||||
}
|
||||
```
|
||||
|
||||
### Updates
|
||||
|
||||
As mentioned in [Telegram Bot API reference](https://core.telegram.org/bots/api#getting-updates), there are two ways for
|
||||
updates retrieving:
|
||||
|
||||
* Webhooks
|
||||
* Long Polling
|
||||
|
||||
Both of them you could use in your project using [TelegramBotAPI](../TelegramBotAPI/README.md), but here there are
|
||||
several useful extensions for both of them:
|
||||
|
||||
#### Long polling
|
||||
|
||||
The most simple way is Long Polling. The most simple way was mentioned above:
|
||||
|
||||
```kotlin
|
||||
val filter = bot.startGettingFlowsUpdatesByLongPolling(
|
||||
scope = CoroutineScope(Dispatchers.Default)
|
||||
) {
|
||||
// place code from examples here with replacing of `filter` by `this`
|
||||
}
|
||||
```
|
||||
|
||||
Extension `startGettingFlowsUpdatesByLongPolling` was used in this example, but there are a lot of variations of
|
||||
`startGettingOfUpdatesByLongPolling` and others for getting the same result. Usually, it is supposed that you already
|
||||
have created `filter` object (or something like this) and will pass it into extension:
|
||||
|
||||
```kotlin
|
||||
val filter = FlowsUpdatesFilter(64)
|
||||
bot.startGettingOfUpdatesByLongPolling(
|
||||
filter
|
||||
)
|
||||
```
|
||||
|
||||
But also there are extensions which allow to pass lambdas directly:
|
||||
|
||||
```kotlin
|
||||
bot.startGettingOfUpdatesByLongPolling(
|
||||
{
|
||||
println("Received message update: $it")
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
Anyway, it is strictly recommended to pass your `CoroutineScope` object to this method at least for more comfortable
|
||||
management of updates.
|
||||
|
||||
#### WebHooks (currently JVM-only)
|
||||
|
||||
For webhooks there are less number of functions and extensions than for Long Polling (but it is still fully automated):
|
||||
|
||||
```kotlin
|
||||
startListenWebhooks(
|
||||
8081,
|
||||
CIO // require to implement this engine dependency
|
||||
) {
|
||||
// here will be all updates one by one in $it
|
||||
}
|
||||
```
|
||||
|
||||
Besides, there are two additional opportunities:
|
||||
|
||||
* Extension `Route#includeWebhookHandlingInRoute`, which allow you to include webhook processing inside your ktor
|
||||
application without creating of new one server (as it is happening in `startListenWebhooks`)
|
||||
* Extension `RequestsExecutor#setWebhookInfoAndStartListenWebhooks`. It is allow to set up full server (in fact, with
|
||||
`startListenWebhooks`), but also send `SetWebhook` request before and check that it was successful
|
||||
|
||||
### Filters
|
||||
|
||||
There are several filters for flows.
|
||||
|
|
|
|||
|
|
@ -149,53 +149,3 @@ Here was used `okhttp` realisation of client, but there are several others engin
|
|||
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