From 095c91bf39729889e9b27269b7470b8b6b7197db Mon Sep 17 00:00:00 2001 From: InsanusMokrassar Date: Fri, 15 May 2020 00:48:34 +0600 Subject: [PATCH] update readmes with updates handling --- TelegramBotAPI-extensions-api/README.md | 4 ++ TelegramBotAPI-extensions-utils/README.md | 69 ++++++++++++++++++++++- TelegramBotAPI/README.md | 50 ---------------- 3 files changed, 72 insertions(+), 51 deletions(-) diff --git a/TelegramBotAPI-extensions-api/README.md b/TelegramBotAPI-extensions-api/README.md index eeac67ba38..d49094f4d5 100644 --- a/TelegramBotAPI-extensions-api/README.md +++ b/TelegramBotAPI-extensions-api/README.md @@ -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 diff --git a/TelegramBotAPI-extensions-utils/README.md b/TelegramBotAPI-extensions-utils/README.md index b4b1e5bb66..cfcaf41484 100644 --- a/TelegramBotAPI-extensions-utils/README.md +++ b/TelegramBotAPI-extensions-utils/README.md @@ -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. diff --git a/TelegramBotAPI/README.md b/TelegramBotAPI/README.md index 87db0f0558..67536e6141 100644 --- a/TelegramBotAPI/README.md +++ b/TelegramBotAPI/README.md @@ -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