Hello :) It is my libraries docs place and I glad to welcome you here. I hope, this documentation place will help you.
Library was created to give opportunity to launch some things from time to time according to some schedule in runtime of applications.
Here you may find the builder for Krontab templates creation.
Krontab
There are several ways to configure and use this library:
Anyway, to start some action from time to time you will need to use one of extensions/functions:
val kronScheduler = /* creating of KronScheduler instance */;\n\nkronScheduler.doWhile {\n // some action\n true // true - repeat on next time\n}\n
If you want to include krontab in your project, just add next line to your dependencies part:
krontab
implementation \"dev.inmo:krontab:$krontab_version\"\n
Next version is the latest currently for the library:
For old version of Gradle, instead of implementation word developers must use compile.
implementation
compile
Developers can use more simple way to configure repeat times is string. String configuring like a crontab, but with a little bit different meanings:
crontab
/--------------- Seconds\n| /------------- Minutes\n| | /----------- Hours\n| | | /--------- Days of months\n| | | | /------- Months\n| | | | | /----- (optional) Year\n| | | | | | /--- (optional) Timezone offset\n| | | | | | | / (optional) Week days\n* * * * * * 0o *w\n
It is different with original crontab syntax for the reason, that expected that in practice developers will use seconds and minutes with more probability than months (for example) or even years. In fact, developers will use something like:
doWhile(\"/5 * * * *\") {\n println(\"Called\")\n true // true - repeat on next time\n}\n
Another version:
doInfinity(\"/5 * * * *\") {\n println(\"Called\")\n}\n
Both of examples will print Called message every five seconds.
Called
Also, this library currently supports DSL for creating the same goals:
val kronScheduler = buildSchedule {\n seconds {\n from (0) every 5\n }\n}\nkronScheduler.doWhile {\n println(\"Called\")\n true // true - repeat on next time\n}\n
Or
val kronScheduler = buildSchedule {\n seconds {\n 0 every 5\n }\n}\nkronScheduler.doWhile {\n println(\"Called\")\n true // true - repeat on next time\n}\n
val kronScheduler = buildSchedule {\n seconds {\n 0 every 5\n }\n}\nkronScheduler.doInfinity {\n println(\"Called\")\n}\n
All of these examples will do the same things: print Called message every five seconds.
With regular doOnce/doWhile/doInfinity there are two types of their variations: local and timezoned. Local variations (doOnceLocal/doWhileLocal/doInfinityLocal) will pass DateTime as an argument into the block:
doOnce
doWhile
doInfinity
doOnceLocal
doWhileLocal
doInfinityLocal
DateTime
doInfinityLocal(\"/5 * * * *\") {\n println(it) // will print current date time\n}\n
Timezoned variations (doOnceTz/doWhileTz/doInfinityTz) will do the same thing but pass as an argument DateTimeTz:
doOnceTz
doWhileTz
doInfinityTz
DateTimeTz
doInfinityTz(\"/5 * * * * 0o\") {\n println(it) // will print current date time in UTC\n}\n
It is useful in cases when you need to get the time of calling and avoid extra calls to system time.
KronScheduler
*Here there is an important notice, that Work infinity is not exactly infinity. Actually, that means that do while coroutine is alive and in fact executing will be stopped when coroutine became cancelled.
Work infinity
infinity
do while coroutine is alive
Any KronScheduler can be converted to a Flow<DateTime> using extension asFlow:
Flow<DateTime>
asFlow
val kronScheduler = buildSchedule {\n seconds {\n 0 every 1\n }\n}\n\nval flow = kronScheduler.asFlow()\n
So, in this case any operations related to flow are available, and it is expected that they will work correctly. For example, it is possible to use this flow with takeWhile:
takeWhile
flow.takeWhile {\n condition()\n}.collect {\n action()\n}\n
Offsets in this library works via passing parameter ending with o in any place after month config. Currently, there is only one format supported for offsets: minutes of offsets. To use time zones you will need to call next method with DateTimeTz argument or nextTimeZoned method with any KronScheduler instance, but in case if this scheduler is not instance of KronSchedulerTz it will work like you passed just DateTime.
o
month
next
nextTimeZoned
KronSchedulerTz
Besides, in case you wish to use time zones explicitly, you will need to get KronSchedulerTz. It is possible by:
createSimpleScheduler
buildSchedule
KrontabTemplate#toSchedule
KrontabTemplate#toKronScheduler
defaultOffset
SchedulerBuilder#build
Unlike original CRON, here week days:
AND
0-3w
0,1,2,3w
KronScheduler is the simple interface with only one function next. This function optionally get as a parameter DateTime which will be used as start point for the calculation of next trigger time. This function will return the next DateTime when something must happen.
Default realisation (CronDateTimeScheduler) can be created using several ways:
CronDateTimeScheduler
SchedulerBuilder
In the examples below the result of created scheduler will be the same.
Crontab-like syntax
See String format for more info about the crontab-line syntax
This way will be very useful for cases when you need to configure something via external configuration (from file on startup or via some parameter from requests, for example):
val schedule = \"5 * * * *\"\nval scheduler = buildSchedule(schedule)\n\nscheduler.asFlow().onEach {\n // this block will be called every minute at 5 seconds\n}.launchIn(someCoroutineScope)\n
In case of usage builder (lets call it lambda way), you will be able to configure scheduler in more type-safe way:
lambda way
val scheduler = buildSchedule {\n seconds {\n at(5)\n }\n}\n\nscheduler.asFlow().onEach {\n // this block will be called every minute at 5 seconds\n}.launchIn(someCoroutineScope)\n
You are always able to use your own realisation of scheduler. For example:
class RandomScheduler : KronScheduler {\n override suspend fun next(relatively: DateTime): DateTime {\n return relatively + DateTimeSpan(seconds = Random.nextInt() % 60)\n }\n}\n
In the example above we have created RandomScheduler, which will return random next time in range 0-60 seconds since relatively argument.
RandomScheduler
0-60
relatively
As in crontab util, this library have almost the same format of string:
Int
w
ms
0
*/15
30
22
*/5
11
60o
0w
*/2w
4w
0ms
*/150ms
300ms
Example with almost same description:
/-------------------- (0-59) \u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7 Seconds\n| /------------------ (0-59) \u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7 Minutes\n| | /---------------- (0-23) \u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7 Hours\n| | | /-------------- (0-30) \u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7 Days of months\n| | | | /------------ (0-11) \u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7 Months\n| | | | | /---------- (optional, any int) Year\n| | | | | | /-------- (optional) \u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7 Timezone offset\n| | | | | | | /----- (optional, 0-6) \u00b7\u00b7\u00b7 Week days\n| | | | | | | | /-- (optional, 0-999) \u00b7 Milliseconds (0 by default)\n* * * * * * 0o *w 0ms\n
Years, timezone, week days and milliseconds are optional settings. Next snippets are equal:
*/15 * * * *\n*/15 * * * * * // with year\n*/15 * * * * * 0ms // with year and milliseconds\n
Currently the library support next syntax for date/time elements:
{int}-{int}
{int}/{int}
*/{int}
{int}
{other_element},{other_element}
F
f
L
l
Ranges are working like common rangeTo (or ..) in kotlin:
rangeTo
..
0-5 * * * *\n
In the example above scheduler will trigger every second from the beginning of the minute up to fifth second of minute.
Start/step is a little bit more complicated syntax. It means start from the first element, repeat triggering every second element. Examples:
start from the first element, repeat triggering every second element
5/15 * * * *\n
Means that each minute starting from fifth second it will repeat triggering every fifteenth second: 5, 20, 35, 50.
5, 20, 35, 50
Every is more simple syntax and could be explained as a shortcut for 0/{int}. Example:
0/{int}
*/15 * * * *\n
Means that each minute it will repeat triggering every fifteenth second: 0, 15, 30, 45.
0, 15, 30, 45
The most simple syntax. It means, that scheduler will call triggering every time when element was reached:
15 * * * *\n
Means that each minute scheduler will call triggering at the fifteenth second.
All the previous elements can be combined with listing. Lets just see several examples:
0,10 * * * *\n
Will trigger every minute at the 0 and 10 seconds (see Just at the time)
10
0-5,10 * * * *\n
Will trigger every minute from 0 to 5 seconds and at the 10 seconds (see Ranges)
5
0/5 * * * *
0/5,L * * * *
0/15 30 * * *
0/15 30 * * * 500ms
1 2 3 F,4,L 5
1 2 3 F,4,L 5 60o
1 2 3 F,4,L 5 60o 0-2w
1 2 3 F,4,L 5 2021
1 2 3 F,4,L 5 2021 60o
1 2 3 F,4,L 5 2021 60o 0-2w
1 2 3 F,4,L 5 2021 60o 0-2w 500ms
Not very often. It depends on libraries (coroutines, korlibs/klock) updates and on some new awesome, but lightweight, features coming.
First of all, this library will be useful for long uptime applications which have some tasks to do from time to time.
In two words, you should call buildSchedule or createSimpleScheduler:
buildSchedule(\"5 * * * *\").asFlow().collect { /* do something */ }\n
You can read more about syntax in String format section.
Custom KronScheduler
You are always may create your own scheduler. In this section will be presented different ways and examples around standard CronDateTimeScheduler builders buildSchedule. You can read about schedulers in KrontabScheduler
Currently, buildSchedule is the recommended start point for every scheduler. Usually, it is look like:
val scheduler = buildSchedule(\"5 * * * *\")\n
Or:
val scheduler = buildSchedule {\n seconds {\n at(5)\n }\n}\n
On the top of any KronScheduler currently there are several groups of extensions:
All executes are look like do.... All executes are described below:
do...
block
true
Shortcuts are the constants that are initializing in a lazy way to provide preset KronSchedulers. For more info about KrontabScheduler you can read its own page.
KrontabScheduler
AnyTimeScheduler
Every*Scheduler
EverySecondScheduler
KronScheduler.everyMillisecond
KronScheduler.everySecond
EveryMinuteScheduler
KronScheduler.everyMinute
EveryHourScheduler
KronScheduler.hourly
EveryDayOfMonthScheduler
KronScheduler.daily
EveryMonthScheduler
KronScheduler.monthly
EveryYearScheduler
KronScheduler.annually
Here currently there is only one extension for KronScheduler: KronScheduler#asFlow. As a result you will get Flow<DateTime> (in fact SchedulerFlow) which will trigger next emit on each not null next DateTime
KronScheduler#asFlow
SchedulerFlow
emit
In two words, you must add dependency dev.inmo:krontab:$krontab_version to your project. The latest version presented by next badge:
dev.inmo:krontab:$krontab_version
To use this library, you will need to include MavenCentral repository in you project
MavenCentral
mavenCentral()\n
Next snippets must be placed into your dependencies part of build.gradle (for gradle) or pom.xml (for maven).
dependencies
build.gradle
pom.xml
<dependency>\n <groupId>dev.inmo</groupId>\n <artifactId>krontab</artifactId>\n <version>${krontab_version}</version>\n</dependency>\n
It is simple and easy-to-use tool for logging on the most popular platforms in Kotlin Multiplatform:
By default, KSLog is using built-in tools for logging on each supported platform:
java.util.logging.Logger
JVM
android.util.Log
Android
Console
JS
But you always may create your logger and customize as you wish:
KSLog.default = KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->\n // do your logging\n}\n
This library also supports native targets in experimental mode. By default, all native targets will use simple printing in the console
Just use some boring extensions like:
KSLog.i(\"Some message\")\n// OR\nKSLog.i(\"Some tag\", \"Some message\")\n// OR\nKSLog.i(\"Some tag\", \"Some message\", IllegalArgumentException(\"So, that is exception :)\"))\n// OR\nKSLog.i(\"Some optional tag\", Exception(\"Optional\")) { \"Lazy inited message\" }\n// OR\nKSLog.iS(\"Some optional tag\", Exception(\"Optional\")) { \"Lazy inited message for suspendable calculation of text\" }\n// OR EVEN\nKSLog.l(LogLevel.INFO, \"Some tag\", \"Some message\", IllegalArgumentException(\"So, that is exception :)\"))\n// OR\nKSLog.l(LogLevel.INFO, \"Some optional tag\", IllegalArgumentException(\"So, that is exception :)\")) { \"And lazily inited message\" }\n
There are several important \u201cterms\u201d in context of this library:
KSLog.default
KSLog
KSLog.i
KSLog.info
Any.logger
apply
Every logging extension (like KSLog.i) have its analog with lazy inited message text and the same one with suffix S (like KSLog.iS) for the suspendable message calculation.
S
KSLog.iS
Default logger can be created by passing defaultTag and one of variants log level filters: set or minimal loggable level. In JVM you also may setup any logger as base logger for default realizations of KSLog. Besides, you may use your own callback (on any target platform) as output of logging:
defaultTag
val logger = KSLog { logLevel, optionalTag, message, optionalThrowable ->\n println(\"[$logLevel] $optionalTag - $message: $optionalThrowable.stackTraceToString()\")\n}\n
In the example above we will take the logger which will just print incoming data as common output.
logger
implementation \"dev.inmo:kslog:$kslog_version\"\n
<dependency>\n <groupId>dev.inmo</groupId>\n <artifactId>kslog</artifactId>\n <version>${kslog_version}</version>\n</dependency>\n
Message type notice
On this page all the messages will be just simple String, but you may pass any object as the message
String
As has been said in the setup section, this library contains next levels of logging with their default representations on each platform:
Each of these levels have fullname and shortname shortcat extensions:
KSLog.trace
KSLog.t
KSLog.tS
KSLog.debug
KSLog.d
KSLog.dS
KSLog.verbose
KSLog.v
KSLog.vS
KSLog.warning
KSLog.w
KSLog.wS
KSLog.error
KSLog.e
KSLog.eS
KSLog.assert
KSLog.wtf
KSLog.wtfS
And any of these shortcuts may accept one of several arguments combinations:
suspendable
So, when you want to log some expected exception, there are three common ways to do it:
val logger = KSLog.default\n\n// with callback\nlogger.info(tag, throwable) {\n \"Some your message for this event\"\n}\n\n// with suspendable callback\nlogger.infoS(tag, throwable) {\n withContext(Dispatchers.Default) {\n \"Some your message for this event\"\n }\n}\n\n// Just with message\nlogger.info(\"Some your message for this event\", throwable)\n\n// With message and tag as strings\nlogger.info(tag, \"Some your message for this event\", throwable)\n
Of course, any of this calls can be shortenned:
val logger = KSLog.default\n\n// with callback\nlogger.i(tag, throwable) {\n \"Some your message for this event\"\n}\n\n// with suspendable callback\nlogger.iS(tag, throwable) {\n withContext(Dispatchers.Default) {\n \"Some your message for this event\"\n }\n}\n\n// Just with message\nlogger.i(\"Some your message for this event\", throwable)\n\n// With message and tag as strings\nlogger.i(tag, \"Some your message for this event\", throwable)\n
There is special shortcat - for base performLog. In that case the only change is that you will require to pass the LogLevel more obviously:
performLog
LogLevel
val logger = KSLog.default\n\n// with callback\nlogger.log(LogLevel.INFO, tag, throwable) {\n \"Some your message for this event\"\n}\n\n// with suspendable callback\nlogger.logS(LogLevel.INFO, tag, throwable) {\n withContext(Dispatchers.Default) {\n \"Some your message for this event\"\n }\n}\n\n// Just with message\nlogger.log(LogLevel.INFO, \"Some your message for this event\", throwable)\n\n// With message and tag as strings\nlogger.log(LogLevel.INFO, tag, \"Some your message for this event\", throwable)\n
OR
val logger = KSLog.default\n\n// with callback\nlogger.l(LogLevel.INFO, tag, throwable) {\n \"Some your message for this event\"\n}\n\n// with suspendable callback\nlogger.lS(LogLevel.INFO, tag, throwable) {\n withContext(Dispatchers.Default) {\n \"Some your message for this event\"\n }\n}\n\n// Just with message\nlogger.l(LogLevel.INFO, \"Some your message for this event\", throwable)\n\n// With message and tag as strings\nlogger.l(LogLevel.INFO, tag, \"Some your message for this event\", throwable)\n
implementation(\"dev.inmo:kslog:$kslog_version\")\n
The main point in setup in your code is to setup default logger:
KSLog.default = KSLog(\"defaultTag\")\n
You may use custom messageFormatter in any of KSLog factory to customize output of KSLog logging. For example:
messageFormatter
KSLog(\n \"loggingWithCustomFormat\",\n messageFormatter = { level, tag, message, throwable ->\n println(\"[$level] $tag - $message: $throwable\")\n }\n)\n
Additionally you may use one of several different settings:
minLoggingLevel
levels
firstLevel
secondLevel
otherLevels
vararg
In case you are passing minLoggingLevel, the level and more important levels will be passed to logs. For example, when you are settings up your logger as in next snippet:
val logger = KSLog(\n \"exampleTag\",\n minLoggingLevel = LogLevel.INFO\n)\n
The next levels will be logged with logger:
INFO
WARNING
ERROR
ASSERT
It is logger which will call incoming performLogCallback on each logging. This logger can be create simply with one callback:
performLogCallback
KSLog { level, tag, message, throwable ->\n println(\"[$level] $tag - $message: $throwable\")\n}\n
It is simple value class which can be used for zero-cost usage of some tag and calling for KSLog.default. For example, if you will create tag logger with next code:
val logger = TagLogger(\"tagLoggerTag\")\n
The logger will call KSLog.default with the tag tagLoggerTag on each calling of logging.
tagLoggerTag
This pretty simple logger will call its fallbackLogger only in cases when incoming messageFilter will return true for logging:
fallbackLogger
messageFilter
val baseLogger = KSLog(\"base\") // log everything with the tag `base` if not set other\nval filtered = baseLogger.filtered { _, t, _ ->\n t == \"base\"\n}\n
In the example above baseLogger will perform logs in two ways: when it has been called directly or when we call log performing with the tag \"base\" or null. Besides, you can see there extension filtered which allow to create FilterKSLog logger with simple lambda.
baseLogger
\"base\"
null
filtered
FilterKSLog
This logger accepts map of types with the target loggers. You may build this logger with the special simple DSL:
val baseLogger = KSLog(\"base\") // log everything with the tag `base` if not set other\nval typed = buildTypedLogger {\n on<Int>(baseLogger) // log all ints to the baseLogger\n on<Float> { _, _, message, _ ->// log all floats to the passed logger\n println(message.toString()) // just print all floats\n }\n default { level, tag, message, throwable ->\n KSLog.performLog(level, tag, message, throwable)\n }\n}\n
There are two things which can be useful in your code: logger and logTag extensions. logTag is the autocalculated by your object classname tag. logger extension can be used with applying to any object like in the next snippet:
logTag
class SomeClass {\n init {\n logger.i(\"inited\")\n }\n}\n
The code above will trigger calling of logging in KSLog.default with level LogLevel.INFO using tag SomeClass and message \"inited\". As you could have guessed, logger is using TagLogger with logTag underhood and the most expensive operation here is automatical calculation of logTag.
LogLevel.INFO
SomeClass
\"inited\"
TagLogger
For JVM you may setup additionally use java loggers as the second parameter of KSLog factory. For example:
KSLog(\n \"yourTag\"\n Logger.getLogger(\"YourJavaLoggerName\")\n)\n
MicroUtils is a set of libraries to help me (and, I hope, you too) in some routine doings of coding.
MicroUtils
First of all, this library collection is oriented to use next technologies:
Kotlin Coroutines
Kotlin Serialization
Kotlin Exposed
Ktor
Koin
Korlibs
Warning
Due to complexity of this library, it is possible that some things will be missed or inactual. Me and the users of this library will try hard to keep its docs as actual as possible, but in case you will find some inconsistency of docs and library work (signatures, behaviour, API) you may write me directly in my telegram
Generated with gitdiagram and edited then
group=dev.inmo artifact=micro_utils.colors.common package=$group.$artifact central_package=$group/$artifact
Group
$group
ArtifactId
$artifact
Adding dependency:
implementation \"$group:$artifact:latest\"\n
Info
All the samples below will represent HEXAColor with r==0xaa, g==0xff, b==0x00 and a==0xff
HEXAColor
r==0xaa
g==0xff
b==0x00
a==0xff
This package contains mainly one file: HEXAColor. This file contains unified color with HEXA format. It consumes UInt by default constructor and r/g/b/a parameters in other main constructors:
UInt
HEXAColor(0xaaff00ffu) // 0xRGBAu as UInt\nHEXAColor(r = 0xaa, g = 0xff, b = 0x00, a = 0xff)\nHEXAColor(r = 0xaa, g = 0xff, b = 0x00, aOfOne = 1f)\n
Besides, you may use one of converters:
HEXAColor.fromAhex(0xffaaff00u) // 0xARGBu as UInt\nHEXAColor.parse(\"rgba(aa, ff, 00, ff)\")\nHEXAColor.parse(\"rgba(aa, ff, 00)\")\nHEXAColor.parse(\"#af0\")\nHEXAColor.parse(\"#af0f\")\nHEXAColor.parse(\"#aaff00\")\nHEXAColor.parse(\"#aaff00ff\")\n
dev.inmo
micro_utils.colors.common
implementation \"dev.inmo:micro_utils.colors.common:latest\"\n
Package: dev.inmo:micro_utils.resources
dev.inmo:micro_utils.resources
This package aimed to make some multiplatform support for resources of your application. As for now, there is only support for strings. Sample:
object Translations {\n val someVariable = buildStringResource(\n \"Sample default string\"\n ) {\n IetfLang.German variant lazy \"Beispiel f\u00fcr eine Standardzeichenkette\"\n }\n}\n
In this case, you will be able to use it with next logic:
Translation.someVariable.translation(IetfLang.French) // \"Sample default string\" as default one\nTranslation.someVariable.translation(IetfLang.German) // \"Beispiel f\u00fcr eine Standardzeichenkette\" as available variant\nTranslation.someVariable.translation(IetfLang.German.DE) // \"Beispiel f\u00fcr eine Standardzeichenkette\" as available parent variant\n
On Android you may use Configuration (as well as Resources or Context) to get translation for current locale. For example:
Configuration
Resources
Context
val context: Context = // context retrieving\n\ncontext.translation(Translation.someVariable)\n
On JVM platform you usually may use Locale.getDefault() to get Locale object and pass it to translation extension:
Locale.getDefault()
Locale
translation
Translation.someVariable.translation(Locale.getDefault())\nTranslation.someVariable.translation() // Locale.getDefault() hidden\n
dev.inmo:micro_utils.startup.plugin
dev.inmo:micro_utils.startup.launcher
This package contains unified simple Plugin/Launcher tools for separating of your apps parts
Plugin
Launcher
Launching logic:
To define plugin, you must use StartPlugin as supertype for your plugin. Restrictions are simple: plugins must be an object or class with empty constructor. Basic sample is here:
StartPlugin
object
class
object YourPlugin : StartPlugin {\n // Body of your plugin\n}\n
Each plugin may contains to parts:
setupDI
startPlugin
object YourPlugin : StartPlugin {\n override fun Module.setupDI(config: JsonObject) {\n // here you may setup any DI content you wish to be available in context of current Koin module\n }\n override fun startPlugin(koin: Koin) {\n // all staff from setupDI and the same function of other plugins is available in koin\n }\n}\n
Basically, launcher module can be used to start application directly from gradle. Let\u2019s imagine you have this gradle groovy config:
gradle
plugins {\n id 'org.jetbrains.kotlin.jvm'\n id \"org.jetbrains.kotlin.plugin.serialization\"\n id 'application'\n}\n\ndependencies {\n // kotlin and other dependencies\n implementation (\"dev.inmo:micro_utils.startup.launcher:$latest_version\")\n}\n\napplication {\n mainClassName = 'dev.inmo.micro_utils.startup.launcher.MainKt'\n}\n
You will be able to run your project with gradle command ./gradlew run --args=\"path/to/config.json\". config.json must contains something like:
./gradlew run --args=\"path/to/config.json\"
config.json
{\n \"plugins\": [\n \"dev.inmo.micro_utils.startup.launcher.HelloWorldPlugin\"\n ]\n}\n
In current case you will see in logger different logs about launching including log from HelloWorldPlugin with text Hello world.
HelloWorldPlugin
Hello world
Repositories in this library are unified interfaces to work with different types of standard repos:
Default interface for any CRUD-oriented realization of repositories. This type of repos separated to three interfaces:
CRUD
CRUDRepo extends both ReadCRUDRepo and WriteCRUDRepo.
CRUDRepo
ReadCRUDRepo
WriteCRUDRepo
CRUD repos do not support forced placing of data by id when data is not in repo. That means, that you can\u2019t set data in repo by id which absent in the repository.
Contains read-only operations, such as getById, contains. This interface can\u2019t be observed because of it does not suppose any mutable operation.
Contains write-only operations, such as create, update. This interface can be observed via its flows:
By default, all mutating operations consumes Lists of data (List<New> for create, List<Pair<Id, New>> for update and List<Id> for delete), but all they have their extension function-variations with one/two args (like create with New arg)
List
List<New>
create
List<Pair<Id, New>>
update
List<Id>
New
Registered
Id
deleteById
deletedObjectsIdsFlow
Key-value repos has been created to support work with classic key-value stores, where keys are unique across all the repo when values are not unique. As well as all the others types of repos, this one have two basic types: ReadKeyValueRepo and WriteKeyValueRepo
Read repo provides functions like: contains, get or values.
Contains write-only operations. This interface can be observed via its flows:
By default, all mutating operations consumes some collections. For example, set require Map with Keys and Values and do not returns anything. Instead, it will throw notification via onNewValue flow
Map
Key
Value
onNewValue
All the methods on WriteKeyValueRepo have their variances with pairs (for set) or plain varargs.
WriteKeyValueRepo
pairs
set
unset
onValueRemoved
unsetWithValues
This type of repos contains muliple Values by their unique Key. It is not guaranteed, that Values list by any Key will contains only unique values, but in most cases Values list will not contains copies/same objects.
Contains operations for work with value/values getting and checking. For example: count for checking of amount of all values in repo or values by key; get for getting of values by pagination.
pagination
clear
In difference with other repos, not all the methods of write key values repo require collections.
All the methods on WriteKeyValuesRepo have their variances with pairs (for set) or plain varargs.
WriteKeyValuesRepo
add
clearWithValue
remove
removeWithValue
In memory realizations contains several simple variants:
Each realization contains Write and Read parents.
Write
Read
There are several important moments:
It is an abstract repo with abstract functions: updateObject and createObject. Both functions require from realization to create Registered variant from incoming data and both will be called within repo locker.withWriteLock.
updateObject
createObject
You may use functions MapCRUDRepo with passing the callbacks updateObject and createObject which will be used in their realizations of default MapCRUDRepo variant
This library uses koin as preferred DI in MVVM part
Navigation is a library for simple management for your app views (or some other logics). In this library there are several important terms:
Node
Chain
node
RESUMED
chain
There are 4 real statuses:
In fact node will retrieve 6 changes of statuses:
Let\u2019s see the next sample:
we may say several things about the sample above:
PAUSED
So, we would like to add new node in the end of stack:
As we can see, N3 became RESUMED and N2 PAUSED. Let\u2019s try to remove N3:
So, let\u2019s continue with the sample above. Let\u2019s imagine, we need to add new subchain for N2 node. Whole tree will look like:
Here has been created new N2Subchain with N3 node. Both them resumed because of:
We may add new subchain to N1:
So, it has been added, but:
And now we may remove N2 node. This action will trigger next changes:
What has happened:
Stopping in context of navigation means destroying
Traditionally, you need to add dependency to your project. Currently, there are two types of artifacts:
Core
MVVM
implementation \"dev.inmo:navigation.core:$navigation_version\"
implementation \"dev.inmo:navigation.mvvm:$navigation_version\"
After you have added your dependency, you should initialize navigation. There are several important things:
Config
NavigationNodeDefaultConfig
Factory
For example: lets imagine that we have a node Main. Here what should we do to create a node and make it workable in navigation:
Main
data class MainConfig(\n // this id will be used to search an html element by id in JS\n // and Fragment by tag in Android\n override val id: String = \"main\"\n) : NavigationNodeDefaultConfig\n
Both JS and Android platforms require ViewModel for their MVVM node variants, but it can be common as well as MainConfig:
ViewModel
MainConfig
class MainViewModel(\n node: NavigationNode<MainConfig, NavigationNodeDefaultConfig>\n) : ViewModel(\n node\n)\n
// Core variant without MVVM or Compose\nclass MainNode(\n config: MainConfig,\n chain: NavigationChain<NavigationNodeDefaultConfig>,\n) : JsNavigationNode<MainConfig, NavigationNodeDefaultConfig>(\n chain,\n config\n) {\n // Some code\n // In htmlElementStateFlow will be found `HTMLElement` where node should be binded\n}\n// MVVM Compose variant\nclass MainNodeView(\n config: MainConfig,\n chain: NavigationChain<NavigationNodeDefaultConfig>,\n) : View<MainConfig, MainViewModel>(\n config,\n chain\n) {\n // Some code\n // In htmlElementStateFlow will be found `HTMLElement` where node should be binded\n\n @Composable\n override onDraw() {\n Text(\"Hello world\")\n }\n}\n\nobject MainNodeFactory : NavigationNodeFactory<NavigationNodeDefaultConfig> {\n override fun createNode(\n navigationChain: NavigationChain<NavigationNodeDefaultConfig>,\n config: NavigationNodeDefaultConfig\n ): NavigationNode<out NavigationNodeDefaultConfig, NavigationNodeDefaultConfig>? = if (config is MainConfig) {\n MainNode(config, navigationChain) // Or `MainNodeView(config, chain)` for MVVM\n } else {\n null\n }\n}\n
Data below is under TBD
In Android there is one important note: you will not directly work with nodes. In fact it will be required to create special NodeFragment:
NodeFragment
// Core variant\nclass MainFragment : NodeFragment<MainConfig, NavigationNodeDefaultConfig>() {\n // Your code\n // Here will be available: node with type `AndroidFragmentNode`, config: `MainConfig`\n}\n// MVVM Variant\nclass MainViewFragment : ViewFragment<MainViewModel, MainConfig>() {\n // Will be available also `viewModel` via koin `lazyInject`\n override val viewModelClass\n get() = MainViewModel::class\n}\n
Initialization is different on the platforms, so, lets take a look at each one.
In JavaScript it looks like:
JavaScript
initNavigation<NavigationNodeDefaultConfig>(\n ConfigHolder.Chain( // (1)\n ConfigHolder.Node( // (2)\n MainConfig(), // (3)\n null, // (4)\n listOf() // (5)\n ),\n ),\n configsRepo = CookiesNavigationConfigsRepo( // (6)\n Json {\n ignoreUnknownKeys = true\n serializersModule = SerializersModule {\n polymorphic(NavigationNodeDefaultConfig::class, MainConfig::class, MainConfig.serializer()) // (7)\n }\n },\n ConfigHolder.serializer(NavigationNodeDefaultConfig::class.serializer())\n ),\n dropRedundantChainsOnRestore = true, // (8)\n nodesFactory = MainNodeFactory, // (9)\n)\n
ConfigHolder.Node
cookies
localStorage
val factories: List<NavigationNodeFactory<NavigationNodeDefaultConfig>>\nNavigationNodeFactory<NavigationNodeDefaultConfig> { chainHolder, config ->\n factories.firstNotNullOfOrNull { it.createNode(chainHolder, config) }\n}\n
PlaguBot is a small framework for unifying developing of modules of bots. It is built with two parts:
Plugin is a partially independent part of bot. Plugin have several parts:
setupBotClient
TelegramBot
single
PlaguBot
setupBotPlugin
buildBehaviourWithFSM
Plugin realization should be an object or class with empty constructor.
Most important of bot is main function (full reference: dev.inmo.plagubot.AppKt). It consumes one argument - path to config.
main
dev.inmo.plagubot.AppKt
Bot is initializing with the next algorithm:
OLD
There are several important opportunities out of the box:
You may access database in your plugin via koin in setupBotPlugin or as parameter in setupDI:
object YourPlugin : Plugin {\n // ...\n override fun Module.setupDI(\n database: Database, // database\n params: JsonObject\n ) {\n // ...\n }\n}\n
It is simple Exposed database and you may use it in your tables.
As you may see, in the setupDI function we also have params parameter with source configuration json. In case you wish to declare and work with your own config in plugin, you may use next snippet:
params
object YourPlugin : Plugin {\n @Serializable\n data class MyConfig(\n val param1: String,\n val param2: Int,\n )\n // ...\n override fun Module.setupDI(\n database: Database, // database\n params: JsonObject\n ) {\n single {\n get<Json>().decodeFromJsonElement(MyConfig.serializer(), params) // register from root (1)\n }\n // OR\n single {\n get<Json>().decodeFromJsonElement(MyConfig.serializer(), params[\"yourplugin\"]!!) // register from field \"yourplugin\" (2)\n }\n // ...\n }\n\n override suspend fun BehaviourContext.setupBotPlugin(\n koin: Koin\n ) {\n koin.get<MyConfig>() // getting of registered config\n }\n}\n
{\n \"params1\": \"SomeString\",\n \"params2\": 42\n}\n
{\n \"yourplugin\": {\n \"params1\": \"SomeString\",\n \"params2\": 42\n }\n}\n
Out of the box you may setup several things in bot:
StatesManager<State>
DefaultStatesManagerRepo<State>
OnStartContextsConflictResolver
OnUpdateContextsConflictResolver
StateHandlingErrorHandler<State>
// Your plugin\n override fun Module.setupDI(database: Database, params: JsonObject) {\n single<StatesManager<State>> {\n // Your StatesManager<State> initialization\n }\n }\n
// Your plugin\n override fun Module.setupDI(database: Database, params: JsonObject) {\n single<DefaultStatesManagerRepo<State>> {\n // Your DefaultStatesManagerRepo<State> initialization\n }\n }\n
// Your plugin\n override fun Module.setupDI(database: Database, params: JsonObject) {\n singleWithRandomQualifier<OnStartContextsConflictResolver> {\n OnStartContextsConflictResolver { old, new ->\n // null|true|false\n }\n }\n }\n
// Your plugin\n override fun Module.setupDI(database: Database, params: JsonObject) {\n singleWithRandomQualifier<OnUpdateContextsConflictResolver> {\n OnUpdateContextsConflictResolver { old, new, currentStateOnContext ->\n // null|true|false\n }\n }\n }\n
// Your plugin\n override fun Module.setupDI(database: Database, params: JsonObject) {\n single<StateHandlingErrorHandler<State>> {\n StateHandlingErrorHandler<State> { state, throwable ->\n // null or State\n }\n }\n }\n
There are several public services I am hosting or have created:
KrontabSctring
Hello! This is a set of libraries for working with Telegram Bot API.
There are several things you need to do to launch examples below:
mavenCentral()
implementation \"dev.inmo:tgbotapi:$tgbotapi_version\"
tgbotapi_version
More including instructions available here. Other configuration examples:
suspend fun main() {\n val bot = telegramBot(TOKEN)\n\n bot.buildBehaviourWithLongPolling {\n println(getMe())\n\n onCommand(\"start\") {\n reply(it, \"Hi:)\")\n }\n }.join()\n}\n
In this example you will see information about this bot at the moment of starting and answer with Hi:) every time it gets message /start
Hi:)
/start
suspend fun main() {\n val bot = telegramBot(TOKEN)\n\n val flowsUpdatesFilter = FlowsUpdatesFilter()\n bot.buildBehaviour(flowUpdatesFilter = flowsUpdatesFilter) {\n println(getMe())\n\n onCommand(\"start\") {\n reply(it, \"Hi:)\")\n }\n\n retrieveAccumulatedUpdates(this).join()\n }\n}\n
The main difference with the previous example is that bot will get only last updates (accumulated before bot launch and maybe some updates it got after launch)
suspend fun main() {\n val bot = telegramBot(TOKEN)\n\n bot.buildBehaviourWithLongPolling {\n println(getMe())\n\n val nameReplyMarkup = ReplyKeyboardMarkup(\n matrix {\n row {\n +SimpleKeyboardButton(\"nope\")\n }\n }\n )\n onCommand(\"start\") {\n val photo = waitPhoto(\n SendTextMessage(it.chat.id, \"Send me your photo please\")\n ).first()\n\n val name = waitText(\n SendTextMessage(\n it.chat.id,\n \"Send me your name or choose \\\"nope\\\"\",\n replyMarkup = nameReplyMarkup\n )\n ).first().text.takeIf { it != \"nope\" }\n\n sendPhoto(\n it.chat,\n photo.mediaCollection,\n entities = buildEntities {\n if (name != null) regular(name) // may be collapsed up to name ?.let(::regular)\n }\n )\n }\n }.join()\n}\n
You may find examples in this project. Besides, you are always welcome in our chat.
Failed to load class \"org.slf4j.impl.StaticLoggerBinder\"
SLF4J: Failed to load class \"org.slf4j.impl.StaticLoggerBinder\".\nSLF4J: Defaulting to no-operation (NOP) logger implementation\nSLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.\n
This error is just a warning about the absence of slf4j setup. You may fix this error by following to stackoverflow answer
BehaviourBuilder
You may create subcontext with BehaviourBuilder.createSubContextAndDoWithUpdatesFilter and pass there updatesUpstreamFlow parameter with any operations over parent behaviour builder:
BehaviourBuilder.
createSubContextAndDoWithUpdatesFilter
updatesUpstreamFlow
buildBehaviourWithLongPolling {\n createSubContextAndDoWithUpdatesFilter(\n updatesUpstreamFlow = filter { /* some condition */ },\n stopOnCompletion = false // disable stopping of sub context after setup\n ) {\n onCommand() //...\n }\n}\n
updatesUpstreamFlow = filter { it.sourceChat() ?.id == requiredChatId || it.sourceUser() ?.id == requiredUserId }\n
In this library we are using KSLog for logging of events in telegram bots. There are several ways to set it up and configure.
// (1)\nsetDefaultKSLog(\n KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->\n println(defaultMessageFormatter(level, tag, message, throwable))\n }\n)\n\n// (2)\nDefaultKTgBotAPIKSLog = KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->\n println(defaultMessageFormatter(level, tag, message, throwable))\n}\n\n// (3)\nval bot = telegramBot(YOUR_TOKEN) {\n logger = KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->\n println(defaultMessageFormatter(level, tag, message, throwable))\n }\n}\n
KtorRequestsExecutor
telegrabBot
In the telegram system there are two types of keyboards:
Low-level way to create keyboard looks like in the next snippet:
ReplyKeyboardMarkup(\n matrix {\n row {\n add(SimpleKeyboardButton(\"Simple text\"))\n // ...\n }\n // ...\n }\n)\n
In case you wish to create inline keyboard, it will look like the same as for reply keyboard. But there is another way. The next snippet will create the same keyboard as on the screenshots above:
// reply keyboard\nreplyKeyboard {\n row {\n simpleButton(\"7\")\n simpleButton(\"8\")\n simpleButton(\"9\")\n simpleButton(\"*\")\n }\n row {\n simpleButton(\"4\")\n simpleButton(\"5\")\n simpleButton(\"6\")\n simpleButton(\"/\")\n }\n row {\n simpleButton(\"1\")\n simpleButton(\"2\")\n simpleButton(\"3\")\n simpleButton(\"-\")\n }\n row {\n simpleButton(\"0\")\n simpleButton(\".\")\n simpleButton(\"=\")\n simpleButton(\"+\")\n }\n}\n\n// inline keyboard\ninlineKeyboard {\n row {\n dataButton(\"Get random music\", \"random\")\n }\n row {\n urlButton(\"Send music to friends\", \"https://some.link\")\n }\n}\n
Bot API allows you to send live locations and update them during their lifetime. In this library there are several ways to use this API:
In the Bot API there is no independent sendLiveLocation method, instead it is suggested to use sendLocation with setting up live_period. In this library in difference with original Bot API live location is special request. It was required because of in fact live locations and static locations are different types of location info and you as bot developer may interact with them differently.
sendLiveLocation
live_period
Anyway, in common case the logic looks like:
In difference with sendLiveLocation, startLiveLocation using LiveLocationProvider. With this provider you need not to handle chat and message ids and keep some other data for location changes. Instead, you workflow with provider will be next:
Besides, LiveLocationProvider contains different useful parameters about live location
LiveLocationProvider
This way of live locations handling is based on coroutines Flow and allow you to pass some external Flow with EditLiveLocationInfo. So, workflow:
Flow
flow {\n var i = 0\n while (isActive) {\n val newInfo = EditLiveLocationInfo(\n latitude = i.toDouble(),\n longitude = i.toDouble(),\n replyMarkup = flatInlineKeyboard {\n dataButton(\"Cancel\", \"cancel\")\n }\n )\n emit(newInfo)\n i++\n delay(10000L) // 10 seconds\n }\n}\n
val currentMessageState = MutableStateFlow<ContentMessage<LocationContent>?>(null)\n
handleLiveLocation(\n it.chat.id,\n locationsFlow,\n sentMessageFlow = FlowCollector { currentMessageState.emit(it) }\n)\n// this code will be called after `locationsFlow` will ends\n
scope.launch {\n handleLiveLocation(\n it.chat.id,\n locationsFlow,\n sentMessageFlow = FlowCollector { currentMessageState.emit(it) }\n )\n}\n// this code will be called right after launch will be completed\n
See our example to get more detailed sample
For the text creating there are several tools. The most simple one is to concatenate several text sources to make list of text sources as a result:
val sources = \"Regular start of text \" + bold(\"with bold part\") + italic(\"and italic ending\")\n
But there is a little bit more useful way: entities builder:
val items = (0 until 10).map { it.toString() }\nbuildEntities(\" \") {// optional \" \" auto separator which will be pasted between text sources\n +\"It is regular start too\" + bold(\"it is bold as well\")\n items.forEachIndexed { i, item ->\n if (i % 2) {\n italic(item)\n } else {\n strikethrough(item)\n }\n }\n}\n
In the code above we are creating an items list just for demonstrating that inside of buildEntities body we may use any operations for cunstructing our result list of TextSources. As a result, will be created the list which will looks like in telegram as \u201cIt is regular start too it is bold as well 0 ~~1~~ 2 ~~3~~ 4 ~~5~~ 6 ~~7~~ 8 ~~9~~\u201d.
TextSource
This guide will help you choose the right keyboard for your needs and show you various API facilities available in the library to support your choice.
The first thing you need to know is that there are two types of keyboards available in the Telegram Bot API: reply and inline keyboards.
Resize option
In the screenshots above (and in the most others) you may see usage of reply keyboards without resize_keyboard. In case you will use resize_keyboard = true the keyboard will be smaller.
resize_keyboard
resize_keyboard = true
Note the differences in the way these keyboards are shown to a user.
A reply keyboard is shown under the message input field. It replaces the device\u2019s native input method on a mobile device.
An inline keyboard is shown as a part of the message in the chat.
When a user clicks on a simple reply keyboard button, its text is just sent in the chat.
When a user clicks on a simple inline keyboard button, nothing is sent to the chat. Instead, a callback query (a fancy way to say \u201ca request\u201d) is sent directly to the bot and the button is highlighted. It will stay highlighted until the bot acks the callback.
It\u2019s a common mistake to forget to handle callback queries
It leads to the buttons being highlighted for long periods of time, which leads to a bad user experience. Don\u2019t forget to handle these callbacks!
As new messages arrive, a reply keyboard will stay there, while the inline keyboard will stick to the message and move with it.
Ups\u2026 The reply keyboard is now far away from the message it was sent with.
Actually, they are two different unrelated entities now: the original message and the reply keyboard. A reply keyboard persists until you explicitly remove it or replace it with a different one.
It\u2019s a common mistake to forget to remove or replace reply keyboards
It leads to the keyboards being shown forever. Don\u2019t forget to remove reply keyboards when you don\u2019t need them anymore!
You also may use option one_time_keyboard and the keyboard will be automatically removed after user interaction
one_time_keyboard
An inline keyboard could also be removed or changed by editing the original message it was attached to.
Keyboards are not limited to text only. They could be used to ask users for different things, like payments, locations, phone numbers, etc. They could be used to open arbitrary URLs or web apps. Telegram clients process these buttons and interact with the users in the appropriate ways.
For the full list of options, see the official documentation on reply and inline keyboards.
Now, that you know the basics, let\u2019s see how to use the library.
In Telegram Bot API keyboards are sent to the user as a part of an interaction via the reply_markup parameter. More specifically, this parameter is available:
reply_markup
sendXXX
sendMessage
sendPhoto
sendSticker
copyMessage
editMessageXXX
editMessageText
editMessageCaption
editMessageReplyMarkup
stopXXX
stopMessageLiveLocation
Tip
editMessageReplyMarkup is specifically designed to edit a message\u2019s inline keyboard.
Sending inline keyboards is also supported in inline mode through the reply_markup parameter of the InlineQueryResult type and its inheritors. However, this inline mode is unrelated to the inline keyboards.
InlineQueryResult
The reply_markup parameter accepts four different types. Two of them \u2014 ReplyKeyboardMarkup and InlineKeyboardMarkup \u2014 correspond to the reply and inline keyboards respectively. The ReplyKeyboardRemove type is used to remove reply keyboards, but it\u2019s not a keyboard itself. The last one, ForceReply, is used to force users to reply to the bot. It is not a keyboard either, but yet another dirty hack employed by the Telegram Bot API.
ReplyKeyboardMarkup
InlineKeyboardMarkup
ReplyKeyboardRemove
ForceReply
Now, in the library, the WithReplyMarkup is a marker interface for all the interactions which could have a replyMarkup (represents reply_markup) parameter. It is extended by the ReplyingMarkupSendMessageRequest, and then, finally, by classes like SendTextMessage. This, basically, corresponds to the Telegram Bot API.
WithReplyMarkup
replyMarkup
ReplyingMarkupSendMessageRequest
SendTextMessage
Note
You may see all the inheritors of WithReplyMarkup interfaces in the corresponding KDoc
The other way to send a keyboard is through the replyMarkup parameter of the numerous extension methods, like sendMessage. Those are just convenient wrappers around general interaction classes, like the aforementioned SendTextMessage.
As we already know, keyboards consist of buttons. Button classes reside in the dev.inmo.tgbotapi.types.buttons package.
dev.inmo.tgbotapi.types.buttons
The base class for the reply keyboard buttons is the KeyboardButton. The base class for the inline keyboard buttons is the InlineKeyboardButton.
KeyboardButton
InlineKeyboardButton
See their inheritors for the full list of the available buttons. The names are pretty self-explanatory and correspond to the Telegram Bot API.
For example, to send a simple reply keyboard button, use the SimpleKeyboardButton class. To request a contact from the user through the reply, use the RequestContactKeyboardButton class. To attach a URL button to the message, use the URLInlineKeyboardButton. And to attach a callback button, use the CallbackDataInlineKeyboardButton.
SimpleKeyboardButton
RequestContactKeyboardButton
URLInlineKeyboardButton
CallbackDataInlineKeyboardButton
You get the idea.
So, to send a reply keyboard use the following code:
bot.sendMessage(\n chatId = chat,\n text = \"What is the best Kotlin Telegram Bot API library?\",\n replyMarkup = ReplyKeyboardMarkup(\n keyboard = listOf(\n listOf(\n SimpleKeyboardButton(\"ktgbotapi\"),\n ),\n )\n )\n)\n
And here is how you send a basic inline keyboard:
bot.sendMessage(\n chatId = chat,\n text = \"ktgbotapi is the best Kotlin Telegram Bot API library\",\n replyMarkup = InlineKeyboardMarkup(\n keyboard = listOf(\n listOf(\n CallbackDataInlineKeyboardButton(\"I know\", \"know\"),\n URLInlineKeyboardButton(\"Learn more\", \"https://github.com/InsanusMokrassar/ktgbotapi\")\n ),\n )\n ),\n)\n
When we\u2019re done with this simple quiz, we can remove the keyboard with the following code:
bot.sendMessage(\n chatId = chat,\n text = \"You're goddamn right!\",\n replyMarkup = ReplyKeyboardRemove()\n)\n
Don\u2019t forget to remove the reply keyboards!
Buttons in keyboards are arranged in matrices, i.e. two-dimensional arrays, or, to say in layperson\u2019s terms, rows and columns. In contrast to the matrices you\u2019ve learned in school, keyboards are not always necessarily square. Try it:
bot.sendMessage(\n chatId = chat,\n text = \"In contrast to the matrices you've learned in school, keyboards are not always necessary square.\",\n replyMarkup = InlineKeyboardMarkup(\n keyboard = listOf(\n listOf(\n CallbackDataInlineKeyboardButton(\"1\", \"1\"),\n CallbackDataInlineKeyboardButton(\"2\", \"2\"),\n CallbackDataInlineKeyboardButton(\"3\", \"3\"),\n ),\n listOf(\n CallbackDataInlineKeyboardButton(\"4\", \"4\"),\n CallbackDataInlineKeyboardButton(\"5\", \"5\"),\n ),\n listOf(\n CallbackDataInlineKeyboardButton(\"6\", \"6\"),\n )\n )\n )\n)\n
This way of building matrices is not very convenient, so the library provides a few eloquent DSLs to simplify that.
First, there are matrix and row, so the keyboard above can be built like this:
matrix
row
bot.sendMessage(\n chatId = chat,\n text = \"DSLs are sweet!\",\n replyMarkup = InlineKeyboardMarkup(\n keyboard = matrix {\n row {\n +CallbackDataInlineKeyboardButton(\"1\", \"1\")\n +CallbackDataInlineKeyboardButton(\"2\", \"2\")\n +CallbackDataInlineKeyboardButton(\"3\", \"3\")\n }\n row(\n CallbackDataInlineKeyboardButton(\"4\", \"4\"),\n CallbackDataInlineKeyboardButton(\"5\", \"5\"),\n )\n row {\n +CallbackDataInlineKeyboardButton(\"6\", \"6\")\n }\n },\n )\n)\n
Those plus signs are mandatory.
There are two different row functions here. Can you spot the difference?
A single-row matrix can be built with a flatMatrix:
flatMatrix
flatMatrix {\n +CallbackDataInlineKeyboardButton(\"1\", \"1\")\n +CallbackDataInlineKeyboardButton(\"2\", \"2\")\n +CallbackDataInlineKeyboardButton(\"3\", \"3\")\n +CallbackDataInlineKeyboardButton(\"4\", \"4\")\n +CallbackDataInlineKeyboardButton(\"5\", \"5\")\n}\n
But the most convenient way to build a simple keyboard is to use the constructor-like methods: InlineKeyboardMarkup and ReplyKeyboardMarkup. Note, that they are named just like the corresponding constructor, but take a vararg of buttons. They create flat matrices, i.e. single rows.
Finally, there are inlineKeyboard and replyKeyboard
inlineKeyboard
replyKeyboard
DSL methods above rely on Kotlin\u2019s feature of receivers and extensions. So, the magic is done by MatrixBuilder and RowBuilder. That\u2019s why you must use the plus sign to add buttons to the matrix: it\u2019s just an overloaded operator call, another cool Kotlin feature widely used to create sweet DSLs.
MatrixBuilder
RowBuilder
Another bonus of using these DSLs is button builders, like payButton, dataButton, and urlButton:
payButton
dataButton
urlButton
bot.sendMessage(\n chatId = chat,\n text = \"All in one!\",\n replyMarkup = InlineKeyboardMarkup(\n keyboard = matrix {\n row {\n payButton(\"Send money\")\n dataButton(\"Ok\", \"ok\")\n urlButton(\"Google\", \"https://google.com\")\n }\n },\n )\n)\n
Reply keyboard builders provide similar extensions, e.g. requestLocationButton.
requestLocationButton
So, choose the style you like \u2014 from plain Kotlin lists to sweet DSLs \u2014 and use it!
Working with keyboards is not something special in Telegram Bot API. As you have already seen, keyboards are just message parameters. Similarly, keyboard interactions are represented by regular Updates. I.e. when a user interacts with a keyboard, the bot receives an update.
On the other hand, the library is heavily typed, so the actual type of update you would receive varies.
As it was said, reply keyboards cause Telegram clients to send regular messages back to the bot. Peruse this example:
bot.buildBehaviourWithLongPolling {\n bot.sendMessage(\n chatId = chat,\n text = \"\ud83d\udc6e Turn in your accomplices or be prepared for a lengthy \ud83c\udf46 incarceration \u26d3 \ud83d\udc4a \u203c\",\n replyMarkup = replyKeyboard {\n +SimpleKeyboardButton(\n \"I ain't no rat! \ud83d\udeab\ud83d\udc00\ud83e\udd10\ud83d\ude45\"\n )\n +RequestUserKeyboardButton(\n \"Rat out \ud83d\udc00 a friend \ud83d\udc64\",\n KeyboardButtonRequestUser.Common(RequestId.random())\n )\n +RequestChatKeyboardButton(\n \"Rat out \ud83d\udc00 a group of friends \ud83d\udc65\",\n KeyboardButtonRequestChat.Group(RequestId.random())\n )\n }\n )\n\n onText { message: CommonMessage<TextContent> ->\n assert(message.text == \"I ain't no rat! \ud83d\udeab\ud83d\udc00\ud83e\udd10\ud83d\ude45\")\n bot.reply(\n to = message,\n text = \"Good, you're going to jail alone! \u26d3\ud83e\uddd1\u26d3\",\n replyMarkup = ReplyKeyboardRemove()\n )\n }\n\n onUserShared { message: PrivateEventMessage<UserShared> ->\n bot.reply(\n to = message,\n text = \"Haha, you and you friend are both going to jail! \u26d3\ud83d\udc6c\u26d3\",\n replyMarkup = ReplyKeyboardRemove()\n )\n }\n\n onChatShared { message: PrivateEventMessage<ChatShared> ->\n bot.reply(\n to = message,\n text = \"Haha, now you're all going to jail! \u26d3\ud83d\udc68\u200d\ud83d\udc66\u200d\ud83d\udc66\u26d3\",\n replyMarkup = ReplyKeyboardRemove()\n )\n }\n}.join()\n
Read more about buildBehaviourWithLongPolling here
buildBehaviourWithLongPolling
I hope you get the idea: the bot acts like a cop and asks the user to rat out his friends via a reply keyboard (it\u2019s an imaginary situation, of course). The user may refuse to cooperate, rat out a single friend or the whole imaginary group. The bot receives the user\u2019s choices as regular updates, the code above has explicit types (generally optional in Kotlin) and an assert to demonstrate this.
And here is how it works (the user selects the options in the order):
Note how you handle reply keyboards: you process regular messages. For instance, a simple text button sends a regular text message indistinguishable from a case when a user simply types the same text manually.
And don\u2019t be a rat in real life: remove the keyboards with the ReplyKeyboardRemove after you\u2019ve received the input! Otherwise, a keyboard will stay there indefinitely.
Finally, to master the keyboards, you need to know how to handle the inline ones.
Again, let\u2019s explore the example. Imagine you\u2019re making a quiz where users are given a question and a set of answers. Additionally, users are given a link to the wiki page to help with the question and a Google button.
The quiz could be implemented this way:
// A simple data class to represent a question\nval question = Question(\n image = \"https://upload.wikimedia.org/wikipedia/commons/a/a5/Tsunami_by_hokusai_19th_century.jpg\",\n question = \"Who painted this?\",\n answers = listOf(\n Answer(\"Hokusai\", correct = true),\n Answer(\"Sukenobu\"),\n Answer(\"Ch\u014dshun\"),\n Answer(\"Kiyonobu I\"),\n ),\n wiki = \"https://en.wikipedia.org/wiki/Ukiyo-e\",\n)\n\nbot.buildBehaviourWithLongPolling {\n bot.sendPhoto(\n chatId = chat,\n fileId = InputFile.fromUrl(question.image),\n text = question.question,\n replyMarkup = inlineKeyboard {\n // First row: answers\n row {\n for (answer in question.answers.shuffled()) {\n dataButton(\n text = answer.answer,\n data = \"${answer.answer}:${answer.correct}\",\n )\n }\n }\n\n // Second row: help buttons\n row {\n urlButton(\"Wiki \ud83d\udc81\", question.wiki)\n webAppButton(\"Google \ud83d\udd0d\", \"https://google.com\")\n }\n }\n )\n\n onDataCallbackQuery { callback: DataCallbackQuery ->\n val (answer, correct) = callback.data.split(\":\")\n\n if (correct.toBoolean()) {\n bot.answerCallbackQuery(\n callback,\n text = \"$answer is a \u2705 correct answer!\",\n showAlert = true\n )\n } else {\n bot.answerCallbackQuery(\n callback,\n text = \"\u274c Try again, $answer is not a correct answer\u2026\",\n showAlert = true\n )\n }\n }\n}.join()\n
A few important things to note here.
First, the data buttons (they have the CallbackDataInlineKeyboardButton type, but in the code we used a neat DSL) must have unique data. If the data is not unique, Telegram clients will highlight all the buttons with the same data when a user clicks on one of them. Guess how I know that? Well, it\u2019s not in the docs, so trial and error is the only way to learn it (and many other things about the Telegram Bot API).
data
Second, the way you handle inline keyboards is different from the way you handle reply keyboards. Bot API will send updates with a callback_query field populated. This field, of a CallbackQuery type, represents incoming callbacks from callback buttons in inline keyboards. The library turns them into multiple callback types, like the DataCallbackQuery we used in the example. Finally, to handle these callbacks you could use onDataCallbackQuery. Alternatively, if you\u2019re not using any DSLs, you have to handle the CallbackQueryUpdate update type.
callback_query
CallbackQuery
DataCallbackQuery
onDataCallbackQuery
CallbackQueryUpdate
Third, the buttons got highlighted when a user clicks on them. When you\u2019re done with the callback, you need to answer it, by using the answerCallbackQuery function. Otherwise, the button will remain highlighted. Telegram clients will eventually remove the highlight, but it\u2019s still frustrating.
answerCallbackQuery
Finally, you could choose between two styles of acknowledgment: a simple toast-like message or a modal alert. The showAlert flag controls this behavior.
showAlert
And here is the demo of the quiz:
Today we\u2019ve learned how to use keyboards in Telegram bots. There are two types of keyboards: reply and inline. Reply keyboards replace the device\u2019s keyboard and make clients send a message with the predefined content. Inline keyboards are buttons attached to messages. Clicking on them causes the client to send a callback to the bot. In both scenarios the bot receives an update of a corresponding type and has to acknowledge the keayboard interaction for the client to work properly.
There are several places you need to visit for starting work with any Telegram Bot framework on any language:
Anyway, the most important link is How do I create a bot? inside of Telegram Bot API
Examples info
A lot of examples with using of Telegram Bot API you can find in this github repository
The most simple bot will just print information about itself. All source code you can find in this repository. Our interest here will be concentrated on the next example part:
suspend fun main(vararg args: String) {\n val botToken = args.first()\n val bot = telegramBot(botToken)\n println(bot.getMe())\n}\n
So, let\u2019s get understanding, about what is going on:
suspend fun main(vararg args: String)
suspend
suspend fun main
fun main() = runBlocking {}
val botToken = args.first()
val bot = telegramBot(botToken)
bot
println(bot.getMe())
As a result, we will see in the command line something like
ExtendedBot(id=ChatId(chatId=123456789), username=Username(username=@first_test_ee17e8_bot), firstName=Your bot name, lastName=, canJoinGroups=false, canReadAllGroupMessages=false, supportsInlineQueries=false)\n
There are three projects:
TelegramBotAPI Core
TelegramBotAPI API Extensions
TelegramBotAPI
TelegramBotAPI Utils Extensions
Also, there is an aggregator-version tgbotapi, which will automatically include all projects above. It is most recommended version due to the fact that it is including all necessary tools around TelegramBotAPI Core, but it is optionally due to the possible restrictions on the result methods count (for android) or bundle size
tgbotapi
Examples
You can find full examples info in this repository. In this repository there full codes which are working in normal situation. Currently, there is only one exception when these examples could work incorrectly: you are living in the location where Telegram Bot API is unavailable. For solving this problem you can read Proxy setup part
To use this library, you will need to include Maven Central repository in your project
Maven Central
<repository>\n <id>central</id>\n <name>mavenCentral</name>\n <url>https://repo1.maven.org/maven2</url>\n</repository>\n
Besides, there is developer versions repo. To use it in your project, add the repo in repositories section:
repositories
maven {\n url \"https://git.inmo.dev/api/packages/InsanusMokrassar/maven\"\n}\n
<repository>\n <id>dev.inmo</id>\n <name>InmoDev</name>\n <url>https://git.inmo.dev/api/packages/InsanusMokrassar/maven</url>\n</repository>\n
As tgbotapi_version variable in next snippets will be used variable with next last published version:
implementation \"dev.inmo:tgbotapi:$tgbotapi_version\"\n
<dependency>\n <groupId>dev.inmo</groupId>\n <artifactId>tgbotapi</artifactId>\n <version>${tgbotapi_version}</version>\n</dependency>\n
implementation \"dev.inmo:tgbotapi.core:$tgbotapi_version\"\n
<dependency>\n <groupId>dev.inmo</groupId>\n <artifactId>tgbotapi.core</artifactId>\n <version>${tgbotapi_version}</version>\n</dependency>\n
implementation \"dev.inmo:tgbotapi.api:$tgbotapi_version\"\n
<dependency>\n <groupId>dev.inmo</groupId>\n <artifactId>tgbotapi.api</artifactId>\n <version>${tgbotapi_version}</version>\n</dependency>\n
implementation \"dev.inmo:tgbotapi.utils:$tgbotapi_version\"\n
<dependency>\n <groupId>dev.inmo</groupId>\n <artifactId>tgbotapi.utils</artifactId>\n <version>${tgbotapi_version}</version>\n</dependency>\n
In some locations Telegram Bots API urls will be unavailable. In this case all examples will just throw exception like:
Exception in thread \"main\" java.net.ConnectException: Connection refused\n at sun.nio.ch.SocketChannelImpl.checkConnect(Native Method)\n at sun.nio.ch.SocketChannelImpl.finishConnect(SocketChannelImpl.java:717)\n at io.ktor.network.sockets.SocketImpl.connect$ktor_network(SocketImpl.kt:36)\n at io.ktor.network.sockets.SocketImpl$connect$1.invokeSuspend(SocketImpl.kt)\n at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)\n at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:56)\n at kotlinx.coroutines.scheduling.CoroutineScheduler.runSafely(CoroutineScheduler.kt:571)\n at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.executeTask(CoroutineScheduler.kt:738)\n at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.runWorker(CoroutineScheduler.kt:678)\n at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.run(CoroutineScheduler.kt:665)\n\nProcess finished with exit code 1\n
There are several ways to solve this problem:
First of all, you will need to use one more library:
build.gradle:
implementation \"io.ktor:ktor-client-okhttp:2.3.5\"\n
Dependency note
In the snippet above was used version 2.3.5 which is actual for TelegramBotAPI at the moment of filling this documentation (october 11 2023, TelegramBotAPI version 9.2.2) and you can update version of this dependency in case if it is outdated.
2.3.5
october 11 2023
9.2.2
For configuring proxy for your bot inside your program, you can use next snippet:
val botToken = \"HERE MUST BE YOUR TOKEN\" // (1)\nval bot = telegramBot(botToken) { // (2)\n client = HttpClient(OkHttp) { // (3)\n engine { // (4)\n config { // (5)\n proxy( // (6)\n Proxy( // (7)\n Proxy.Type.SOCKS, // (8)\n InetSocketAddress(\"127.0.0.1\", 1080) // (9)\n )\n )\n }\n }\n }\n}\n
botToken
HttpClient
OkHttp
Socks
\"127.0.0.1\"
1080
You may try to use custom engine for ktor. For example:
// JVM\n// OkHttp engine\n// Socks5 proxy\n\nval bot = telegramBot(botToken) { // (1)\n val proxyHost = \"your proxy host\" // (2)\n val proxyPort = 1080 //your proxy port // (3)\n val username = \"proxy username\" // (4)\n val password = \"proxy password\" // (5)\n\n val proxyAddr = InetSocketAddress(proxyHost, proxyPort) // (6)\n val proxy = Proxy(Proxy.Type.SOCKS, proxyAddr) // (7)\n\n val passwordAuthentication = PasswordAuthentication(\n username,\n password.toCharArray()\n ) // (8)\n Authenticator.setDefault(object : Authenticator() { // (9)\n override fun getPasswordAuthentication(): PasswordAuthentication? { // (10)\n return if (requestingHost.lowercase() == proxyHost.lowercase()) { // (11)\n passwordAuthentication\n } else {\n null\n }\n }\n })\n this.client = HttpClient(OkHttp) { // (12)\n engine { // (13)\n config { // (14)\n proxy(proxy) // (15)\n }\n }\n }\n}\n
Proxy
API extensions is a module which you may include in your project in addition to core part. In most cases this module will allow just use syntax like bot.getUpdates() instead of bot.execute(GetUpdates()), but there are several other things you will achieve with that syntax.
bot.getUpdates()
bot.execute(GetUpdates())
This functionality allow you to build bot in more unified and comfortable way than standard creating with telegramBot function
telegramBot
buildBot(\n \"TOKEN\"\n) {\n proxy = ProxyBuilder.socks(host = \"127.0.0.1\", port = 4001) // just an example, more info on https://ktor.io/docs/proxy.html\n ktorClientConfig = {\n // configuring of ktor client\n }\n ktorClientEngineFactory = {\n // configuring of ktor client engine \n }\n}\n
In standard library requests there are no way to download some file retrieved in updates or after requests. You may use syntax like bot.downloadFile(file) where file is TelegramMediaFile from telegram, FileId or even PathedFile from GetFile request (sources).
bot.downloadFile(file)
file
TelegramMediaFile
FileId
PathedFile
By default, you should handle updates of Live location by your code. But with extension bot#startLiveLocation you may provide all necessary startup parameters and handle updates with just calling updateLocation for retrieved LiveLocationProvider.
updateLocation
There are several things you may read next:
Behaviour builder with FSM is based on the MicroUtils FSM. There are several important things in FSM:
State
StateHandler
StatesMachine have two methods:
StatesMachine
start
startChain
The most based way to create StatesMachine and register StateHandlers looks like in the next snippet:
buildFSM<TrafficLightState> {\n strictlyOn<SomeState> {\n // state handling\n }\n}.start(CoroutineScope(...)).join()\n
Full example
You may find full example of FSM usage in the tests of FSM in MicroUtils
So, you must do next steps before you will launch your bot with FSM:
There are several extensions for TelegramBot to create your bot with FSM:
All of them will take as an callback some object with type CustomBehaviourContextReceiver and will looks like in the next snippet:
telegramBotWithBehaviourAndFSMAndStartLongPolling<YourStateType>(\"BOT_TOKEN\") {\n // here you may use any operations from BehaviourBuilder\n // here you may use any operations from BehaviourContextWithFSMBuilder like strictlyOn and others\n}\n
In the previous pages about updates handling and was mentioned that currently in the most cases you should use Flows. So, there is an improvement for that system which hide direct work with flows and allow you to create more declarative logic of your bot.
There are several things you should know for better understanding of behaviour builder:
on*
BehaviourContext
wait*
As was said above, there is buildBehaviour function which allow you set up your bot logic. Let\u2019s see an example:
val bot = telegramBot(\"TOKEN\")\n\nbot.buildBehaviour {\n onCommand(\"start\") { // creating of trigger\n val message = it\n val content = message.content\n\n reply(message, \"Ok, send me one photo\") // send text message with replying on incoming message\n\n val photoContent = waitPhoto().first() // waitPhoto will return List, so, get first element\n\n val photo = downloadFile(photoContent) // ByteArray of photo\n\n // some logic with saving of photos\n }\n}\n
In most cases there are opportunity to filter some of messages before starting of main logic. Let\u2019s look at this using the example above:
val bot = telegramBot(\"TOKEN\")\n\nbot.buildBehaviour {\n onCommand(\n \"start\",\n initialFilter = {\n it.content.textSources.size == 1 // make sure that user has sent /start without any additions\n }\n ) {\n // ...\n }\n}\n
val bot = telegramBot(\"TOKEN\")\n\nbot.buildBehaviour {\n onCommand(\n \"start\",\n requireOnlyCommandInMessage = true // it is default, but you can overwrite it with `requireOnlyCommandInMessage = false`\n ) {\n // ...\n }\n}\n
In case you wish to start long polling, you have two options:
buildBehaviour
More info
More info about updates retrieving you may read at the Long Polling and Webhooks articles
With prepared bot:
val bot = telegramBot(\"TOKEN\")\n\nbot.buildBehaviourWithLongPolling {\n onCommand(\n \"start\",\n requireOnlyCommandInMessage = true // it is default, but you can overwrite it with `requireOnlyCommandInMessage = false`\n ) {\n // ...\n }\n}\n
Without prepared bot:
telegramBotWithBehaviourAndLongPolling(\"TOKEN\") {\n onCommand(\n \"start\",\n requireOnlyCommandInMessage = true // it is default, but you can overwrite it with `requireOnlyCommandInMessage = false`\n ) {\n // ...\n }\n}\n
val bot = telegramBot(\"TOKEN\")\nval rootContext = bot.buildBehaviour {\n onCommand(\n \"start\",\n requireOnlyCommandInMessage = true // it is default, but you can overwrite it with `requireOnlyCommandInMessage = false`\n ) {\n // ...\n }\n}\n\nbot.longPolling(rootContext) // start listening updates\n
Unfortunatelly, exceptions handling in this library is a bit difficult in some places, but that have at least two reasons: flexibility and usability.
In case you know, where exceptions are happening, you may use several tools for exceptions catching:
If you prefer to receive Result objects instead of some weird callbacks, you may use the next syntax:
Result
safelyWithResult {\n // do something\n}.onSuccess { // will be called if everything is right\n // handle success\n}.onFailure { // will be called if something went wrong\n // handle error\n it.printStackTrace()\n}.getOrThrow() // will return value or throw exception\n
Also there is more simple (in some cases) way to handle exceptions with callbacks:
safely(\n {\n // handle error\n it.printStackTrace()\n null // return value\n }\n) {\n // do something\n}\n
There are two types of handling:
safely(\n {\n it.printStackTrace()\n \"error\"\n }\n) {\n error(\"Hi :)\") // emulate exception throwing\n \"ok\"\n} // result will be with type String\n
safely
safelyWithouExceptions {\n // do something\n} // will returns nullable result type\n
The most simple way to configure exceptions handling is to change CoroutineContext when you are creating your CoroutineScope for bot processing:
CoroutineContext
CoroutineScope
val bot = telegramBot(\"TOKEN\")\n\nbot.buildBehaviour (\n scope = scope,\n defaultExceptionsHandler = {\n it.printStackTrace()\n }\n) {\n // ...\n}\n
val bot = telegramBotWithBehaviour (\n \"TOKEN\",\n scope = scope,\n defaultExceptionsHandler = {\n it.printStackTrace()\n }\n) {\n // ...\n}\n
Here we have used ContextSafelyExceptionHandler class. It will pass default handling of exceptions and will call the block in most cases when something inside of your bot logic has thrown exception.
ContextSafelyExceptionHandler
According to the documentation there are several ways to work with files:
typealias
There are several cases you may need in your app to work with files:
The most simple way to send some file is to get file id and send it. You may get file id from any message with media. For example, if you have received some Message, you may use asCommonMessage conversation to be able to get its content and then convert it to some content with media. Full code here:
content
val message: Message;\n\nval fileId = message.asCommonMessage() ?.withContent<MediaContent>() ?.content ?.media ?.fileId;\n
WAT? O.o
In the code above we get some message, safely converted it to CommonMessage with asCommonMessage, then safely took its content via withContent<MediaContent>() ?.content and then just get its media file id.
CommonMessage
asCommonMessage
withContent<MediaContent>() ?.content
There are three ways to download files:
ByteArray
ByteReadChannelAllocator
[JVM Only]
API
val bot: TelegramBot;\nval fileId: FileId;\nval outputFile: File;\n\nbot.downloadFile(fileId, outputFile)\n
See downloadFile extension docs in the JVM tab to get more available options
There is also way with saving of data into temporal file. That will allow you to do with data whatever you want without high requirements to memory or network connection:
val bot: TelegramBot;\nval fileId: FileId;\n\nval tempFile: File = bot.downloadFileToTemp(fileId)\n
See downloadFileToTemp extension docs to get more available options
val bot: TelegramBot;\nval fileId: FileId;\n\nval bytes: ByteReadChannelAllocator = bot.downloadFileStream(fileId)\n
See downloadFileStream extension docs to get more available options
val bot: TelegramBot;\nval fileId: FileId;\n\nval bytes: ByteReadChannelAllocator = bot.downloadFileStreamAllocator(fileId)\n
See downloadFileStreamAllocator extension docs to get more available options
val bot: TelegramBot;\nval fileId: FileId;\n\nval bytes: ByteArray = bot.downloadFile(fileId)\n
See downloadFile extension docs to get more available options
how does it work?
You may download file with streams or with downloading into the memory first. On low level you should do several things. They are presented in next snippet:
val bot: TelegramBot;\nval fileId: FileId;\n\nval pathedFile: PathedFile = bot.execute(GetFile(fileId))\n\nval downloadedBytes: ByteArray = bot.execute(DownloadFile(pathedFile.filePath))\n
In the snippet above we are getting file PathedFile by its FileId and use it to download file bytes into memory using DownloadFile request.
DownloadFile
You may use almost the same way but with byte read channel allocator:
val bot: TelegramBot;\nval fileId: FileId;\n\nval pathedFile: PathedFile = bot.execute(GetFile(fileId))\n\nval channelAllocator: ByteReadChannelAllocator = bot.execute(DownloadFileStream(pathedFile.filePath))\n\nval byteReadChannel: ByteReadChannel = channelAllocator()\n
And then you may look into ByteReadChannel docs to get more info about what you can do with that.
Several useful links
Of course, in most cases you must be sure that file have correct type.
It is the most simple way to send any media in Telegram, but this way have several restrictions:
JS Restrictions
Sending via file is accessible from all supported platforms, but there is small note about JS - due to restrictions of work with streams and stream-like data (JS have no native support of files streaming) on this platform all the files will be loaded inside of RAM before the sending to the telegram services.
Sending via file is available throw the MultipartFile. There are several wayt to get it:
MultipartFile(\"filename.jpg\") { /* here Input allocation */ }
ByteReadChannel
File
In most cases, sending via files looks like in the next snippet:
val file: File;\n\nbot.sendDocument(chatId, file.asMultipartFile())\n
The base version of library was done a lot of time ago and just got several additions related to improvements, updates in Telegram Bot API or some requests from our community.
There are several important things in context of this library:
So, in most cases all your request calls with simplified api of this library (like bot.getMe()) will looks like bot.execute(GetMe). Result of these calls is defined in type of any request (for example, for GetMe request the result type is ExtendedBot). As a result, you can avoid any extension api (like special API extensions) and use low level request with full controlling of the whole logic flow.
bot.getMe()
bot.execute(GetMe)
As was written above, it will require some request:
val updates = bot.execute(GetUpdates())\n
Result type of GetUpdates request is Update. You may find inheritors of this interface in Update kdocs.
As was said above, you may look into our API extensions in case you wish to use more high-level functions instead of bot.execute(SomeRequest()). Besides, it will be very useful to know more about updates retrieving.
bot.execute(SomeRequest())
As you know, Telegram have the feature named Media Groups. Media groups have several differences with the common messages:
Row updates
In tgbotapi there is no any additional handling of media groups by default and in case you will use simple bot.getUpdates, you will get the list of row updates and media groups will be included in this list as separated messages with MediaGroupPartContent. In that case you may use convertWithMediaGroupUpdates to be able to work with media groups as will be described below
In case you are using standard long polling (one of alternatives is telegramBotWithBehaviourAndLongPolling) or webhooks updates will be converted uner the hood and as a result, you will take media groups as a content in one message:
telegramBotWithBehaviourAndLongPolling(\n \"token\"\n) {\n onVisualGallery { // it: CommonMessage<MediaGroupContent<VisualMediaGroupPartContent>>\n it.content // MediaGroupContent<VisualMediaGroupPartContent>\n it.content.group // List<MediaGroupCollectionContent.PartWrapper<VisualMediaGroupPartContent>>\n it.content.group.forEach { // it: MediaGroupCollectionContent.PartWrapper<VisualMediaGroupPartContent>\n it.messageId // source message id for current media group part\n it.sourceMessage // source message for current media group part\n it.content // VisualMediaGroupPartContent\n println(it.content) // will print current content part info\n }\n }\n}\n
KDocs:
In two words, in difference with row Telegram Bot API, you will take media groups in one message instead of messages list.
One of the most important topics in context of tgbotapi is types conversations. This library is very strong-typed and a lot of things are based on types hierarchy. Lets look into the hierarchy of classes for the Message in 0.35.8:
As you may see, it is a little bit complex and require several tools for types conversation.
as conversations will return new type in case if it is possible. For example, when you got Message, you may use asContentMessage conversation to get message with content:
as
Message
asContentMessage
val message: Message;\nprintln(message.asContentMessage() ?.content)\n
This code will print null in case when message is not ContentMessage, and content when is.
message
ContentMessage
require works like as, but instead of returning nullable type, it will always return object with required type OR throw ClassCastException:
require
ClassCastException
val message: Message;\nprintln(message.requireContentMessage().content)\n
This code will throw exception when message is not ContentMessage and print content when is.
when extensions will call passed block when type is correct. For example:
when
val message: Message;\nmessage.whenContentMessage {\n println(it.content)\n}\n
Code placed above will print content when message is ContentMessage and do nothing when not
Of course, in most cases here we will look up the way of using utils extnsions, but you may read deeper about updates retrieving here.
In most updates retrieving processes there are two components: UpdatesFiler and its inheritor FlowsUpdatesFilter. It is assumed, that you will do several things in your app to handle updates:
UpdatesFilter
flowsUpdatesFilter
Let\u2019s look how it works with the factory above:
// Step 1 - create filter\nval filter = flowsUpdatesFilter {\n // Step 2 - set up handling. In this case we will print any message from group or user in console\n messageFlow.onEach {\n println(it)\n }.launchIn(someCoroutineScope)\n}\n\n// Step 3 - passing updates to filter\nbot.getUpdates().forEach {\n filter.asUpdatesReceiver(it)\n}\n
Some example with long polling has been described above. But it is more useful to use some factories for it. In this page we will look for simple variant with TelegramBot#longPolling. So, with this function, your handling of updates will looks like:
val bot = telegramBot(\"TOKEN\")\n\nbot.longPolling {\n messageFlow.onEach {\n println(it)\n }.launchIn(someCoroutineScope)\n}.join()\n
This example looks like the example above with three steps, but there are several important things here:
.join()
longPolling
Job
cancel
job.cancel()
join
What is next?
As a result you can start listen updates and react on it. Next recommended articles:
Preview reading
It is recommended to visit our pages about UpdatesFilters and Webhooks to have more clear understanding about what is happening in this examples page
Heroku is a popular place for bots hosting. In common case you will need to configure webhooks for your server to include getting updates without problems. There are several things related to heroku you should know:
https://<app name>.herokuapp.com/
System.getenv(\"PORT\").toInt()
Sat Aug 15 5:04:21 +00 2020
Server configuration alternatives
Here will be presented variants of configuration of webhooks and starting server. You always able to set webhook manualy, create your own ktor server and include webhooks handling in it or create and start server with only webhooks handling. More info you can get on page Webhooks
suspend fun main {\n // This subroute will be used as random webhook subroute to improve security according to the recommendations of Telegram\n val subroute = uuid4().toString()\n // Input/Output coroutines scope more info here: https://kotlinlang.org/docs/coroutines-guide.html\n val scope = CoroutineScope(Dispatchers.IO)\n // Here will be automatically created bot and available inside of lambda where you will setup your bot behaviour\n telegramBotWithBehaviour(\n // Pass TOKEN inside of your application environment variables\n System.getenv(\"TOKEN\"),\n scope = scope\n ) {\n // Set up webhooks and start to listen them\n setWebhookInfoAndStartListenWebhooks(\n // Automatic env which will be passed by heroku to the app\n System.getenv(\"PORT\").toInt(),\n // Server engine. More info here: https://ktor.io/docs/engines.html\n Tomcat,\n // Pass URL environment variable via settings of application. It must looks like https://<app name>.herokuapp.com\n SetWebhook(\"${System.getenv(\"URL\").removeSuffix(\"/\")}/$subroute\"),\n // Just callback which will be called when exceptions will happen inside of webhooks\n {\n it.printStackTrace()\n },\n // Set up listen requests from outside\n \"0.0.0.0\",\n // Set up subroute to listen webhooks to\n subroute,\n // BehaviourContext is the CoroutineScope and it is recommended to pass it inside of webhooks server\n scope = this,\n // BehaviourContext is the FlowsUpdatesFilter and it is recommended to pass its asUpdateReceiver as a block to retrieve all the updates\n block = asUpdateReceiver\n )\n // Test reaction on each command with reply and text `Got it`\n onUnhandledCommand {\n reply(it, \"Got it\")\n }\n }\n // Just potentially infinite await of bot completion\n scope.coroutineContext.job.join()\n}\n
// This subroute will be used as random webhook subroute to improve security according to the recommendations of Telegram\nval subroute = uuid4().toString()\nval bot = telegramBot(TOKEN)\nval scope = CoroutineScope(Dispatchers.Default)\n\nval filter = flowsUpdatesFilter {\n messageFlow.onEach {\n println(it) // will be printed \n }.launchIn(scope)\n}\n\nval subroute = UUID.randomUUID().toString() // It will be used as subpath for security target as recommended by https://core.telegram.org/bots/api#setwebhook\n\nval server = bot.setWebhookInfoAndStartListenWebhooks(\n // Automatic env which will be passed by heroku to the app\n System.getenv(\"PORT\").toInt(),\n // Server engine. More info here: https://ktor.io/docs/engines.html\n Tomcat,\n // Pass URL environment variable via settings of application. It must looks like https://<app name>.herokuapp.com\n SetWebhook(\"${System.getenv(\"URL\").removeSuffix(\"/\")}/$subroute\"),\n // Just callback which will be called when exceptions will happen inside of webhooks\n {\n it.printStackTrace()\n },\n // Set up listen requests from outside\n \"0.0.0.0\",\n // Set up subroute to listen webhooks to\n subroute,\n scope = scope,\n block = filter.asUpdateReceiver\n)\n\nserver.environment.connectors.forEach {\n println(it)\n}\nserver.start(false)\n
Long polling is a technology of getting updates for cases you do not have some dedicated server or you have no opportunity to receive updates via webhooks. More about this you can read in wiki.
There are a lot of ways to include work with long polling:
RequestsExecutor#longPollingFlow
RequestsExecutor#startGettingOfUpdatesByLongPolling
RequestsExecutor#longPolling
startGettingOfUpdatesByLongPolling
RequestsExecutor#createAccumulatedUpdatesRetrieverFlow
longPollingFlow
RequestsExecutor#retrieveAccumulatedUpdates
createAccumulatedUpdatesRetrieverFlow
RequestsExecutor#flushAccumulatedUpdates
retrieveAccumulatedUpdates
GetUpdates
RequestsExecutor#getUpdates
longPolling is a simple way to start getting updates and work with bot:
val bot = telegramBot(token)\nbot.longPolling(\n textMessages().subscribe(scope) { // here \"scope\" is a CoroutineScope\n println(it) // will be printed each update from chats with messages\n }\n)\n
The main aim of startGettingOfUpdatesByLongPolling extension was to provide more simple way to get updates in automatic mode:
val bot = telegramBot(token)\nbot.startGettingOfUpdatesByLongPolling(\n {\n println(it) // will be printed each update from chats with messages\n }\n)\n
The other way is to use the most basic startGettingOfUpdatesByLongPolling extension:
val bot = telegramBot(token)\nbot.startGettingOfUpdatesByLongPolling {\n println(it) // will be printed each update\n}\n
Due to the fact, that anyway you will get updates in one format (Update objects), some time ago was solved to create one point of updates filters for more usefull way of updates handling
Update
UpdatesFilter currently have two properties:
asUpdateReceiver
allowedUpdates
Anyway, this filter can\u2019t work with updates by itself. For retrieving updates you should pass this filter to some of getting updates functions (long polling or webhooks).
SimpleUpdatesFilter is a simple variant of filters. It have a lot of UpdateReceiver properties which can be set up on creating of this object. For example, if you wish to get messages from chats (but not from channels), you can use next snippet:
SimpleUpdatesFilter
UpdateReceiver
SimpleUpdatesFilter {\n println(it)\n}\n
A little bit more modern way is to use FlowsUpdatesFilter. It is very powerfull API of Kotlin Coroutines Flows, built-in support of additional extensions for FlowsUpdatesFilter and Flow<...> receivers and opportunity to split one filter for as much receivers as you want. Filter creating example:
FlowsUpdatesFilter
Flow<...>
val scope = CoroutineScope(Dispatchers.Default)\nflowsUpdatesFilter {\n messageFlow.onEach {\n println(it)\n }.launchIn(scope)\n}\n
In cases you need not separate logic for handling of messages from channels and chats there are three ways to combine different flows into one:
plus
flowsUpdatesFilter {\n (messageFlow + channelPostFlow).onEach {\n println(it) // will be printed each message update from channels and chats both\n }.launchIn(scope)\n}\n
aggregateFlows
flowsUpdatesFilter {\n aggregateFlows(\n scope,\n messageFlow,\n channelPostFlow\n ).onEach {\n println(it) // will be printed each message update from channels and chats both\n }.launchIn(scope)\n}\n
flowsUpdatesFilter {\n allSentMessagesFlow.onEach {\n println(it) // will be printed each message update from channels and chats both\n }.launchIn(scope)\n}\n
FlowsUpdatesFilter have a lot of extensions for messages types filtering:
flowsUpdatesFilter {\n textMessages(scope).onEach {\n println(it) // will be printed each message from channels and chats both with content only `TextContent`\n }.launchIn(scope)\n}\n
The same things were created for media groups:
flowsUpdatesFilter {\n mediaGroupMessages(scope).onEach {\n println(it) // will be printed each media group messages list from both channels and chats without filtering of content\n }.launchIn(scope)\n\n mediaGroupPhotosMessages(scope).onEach {\n println(it) // will be printed each media group messages list from both channels and chats with PhotoContent only\n }.launchIn(scope)\n\n mediaGroupVideosMessages(scope).onEach {\n println(it) // will be printed each media group messages list from both channels and chats with VideoContent only\n }.launchIn(scope)\n}\n
Besides, there is an opportunity to avoid separation on media groups and common messages and receive photos and videos content in one flow:
flowsUpdatesFilter {\n sentMessagesWithMediaGroups(scope).onEach {\n println(it) // will be printed each message including each separated media group message from both channels and chats without filtering of content\n }.launchIn(scope)\n\n photoMessagesWithMediaGroups(scope).onEach {\n println(it) // will be printed each message including each separated media group message from both channels and chats with PhotoContent only\n }.launchIn(scope)\n\n videoMessagesWithMediaGroups(scope).onEach {\n println(it) // will be printed each message including each separated media group message from both channels and chats with VideoContent only\n }.launchIn(scope)\n}\n
In telegram bot API there is an opportunity to get updates via webhooks. In this case you will be able to retrieve updates without making additional requests. Most of currently available methods for webhooks are working on ktor server for JVM. Currently, next ways are available for using for webhooks:
Route#includeWebhookHandlingInRoute
Route#includeWebhookHandlingInRouteWithFlows
startListenWebhooks
RequestsExecutor#setWebhookInfoAndStartListenWebhooks
setWebhookInfoAndStartListenWebhooks
It is the most common way to set updates webhooks and start listening of them. Example:
val bot = telegramBot(TOKEN)\n\nval filter = flowsUpdatesFilter {\n // ...\n}\n\nbot.setWebhookInfoAndStartListenWebhooks(\n 8080, // listening port. It is required for cases when your server hidden by some proxy or other system like Heroku\n CIO, // default ktor server engine. It is recommended to replace it with something like `Netty`. More info about engines here: https://ktor.io/servers/configuration.html\n SetWebhook(\n \"address.com/webhook_route\",\n File(\"/path/to/certificate\").toInputFile(), // certificate file. More info here: https://core.telegram.org/bots/webhooks#a-certificate-where-do-i-get-one-and-how\n 40, // max allowed updates, by default is null\n filter.allowedUpdates\n ),\n {\n it.printStackTrace() // optional handling of exceptions\n },\n \"0.0.0.0\", // listening host which will be used to bind by server\n \"subroute\", // Optional subroute, if null - will listen root of address\n WebhookPrivateKeyConfig( // optional config of private key. It will be installed in server to use TLS with custom certificate. More info here: https://core.telegram.org/bots/webhooks#a-certificate-where-do-i-get-one-and-how\n \"/path/to/keystore.jks\",\n \"KeystorePassword\",\n \"Keystore key alias name\",\n \"KeystoreAliasPassword\"\n ),\n scope, // Kotlin coroutine scope for internal transforming of media groups\n filter.asUpdateReceiver\n)\n
If you will use previous example, ktor server will bind and listen url 0.0.0.0:8080/subroute and telegram will send requests to address address.com/webhook_route with custom certificate. Alternative variant will use the other SetWebhook request variant:
0.0.0.0:8080/subroute
address.com/webhook_route
SetWebhook
SetWebhook(\n \"address.com/webhook_route\",\n \"some_file_bot_id\".toInputFile(),\n 40, // max allowed updates, by default is null\n filter.allowedUpdates\n)\n
As a result, request SetWebhook will be executed and after this server will start its working and handling of updates.
This function is working almost exactly like previous example, but this one will not set up webhook info in telegram:
val filter = flowsUpdatesFilter {\n // ...\n}\n\nstartListenWebhooks(\n 8080, // listening port. It is required for cases when your server hidden by some proxy or other system like Heroku\n CIO, // default ktor server engine. It is recommended to replace it with something like `Netty`. More info about engines here: https://ktor.io/servers/configuration.html\n {\n it.printStackTrace() // optional handling of exceptions\n },\n \"0.0.0.0\", // listening host which will be used to bind by server\n \"subroute\", // Optional subroute, if null - will listen root of address\n WebhookPrivateKeyConfig( // optional config of private key. It will be installed in server to use TLS with custom certificate. More info here: https://core.telegram.org/bots/webhooks#a-certificate-where-do-i-get-one-and-how\n \"/path/to/keystore.jks\",\n \"KeystorePassword\",\n \"Keystore key alias name\",\n \"KeystoreAliasPassword\"\n ),\n scope, // Kotlin coroutine scope for internal transforming of media groups\n filter.asUpdateReceiver\n)\n
The result will be the same as in previous example: server will start its working and handling of updates on 0.0.0.0:8080/subroute. The difference here is that in case if this bot must not answer or send some requiests - it will not be necessary to create bot for receiving of updates.
includeWebhookHandlingInRoute
includeWebhookHandlingInRouteWithFlows
For these extensions you will need to start your server manualy. In common case it will look like:
val scope = CoroutineScope(Dispatchers.Default)\n\nval filter = flowsUpdatesFilter {\n // ...\n}\n\nval environment = applicationEngineEnvironment {\n module {\n routing {\n includeWebhookHandlingInRoute(\n scope,\n {\n it.printStackTrace()\n },\n filter.asUpdateReceiver\n )\n }\n }\n connector {\n host = \"0.0.0.0\"\n port = 8080\n }\n}\n\nembeddedServer(CIO, environment).start(true) // will start server and wait its stoping\n
In the example above server will started and binded for listening on 0.0.0.0:8080.
0.0.0.0:8080
This secion contains information about way of getting updates and additional info related to it.