mirror of
https://github.com/InsanusMokrassar/docs.git
synced 2025-12-17 03:35:36 +00:00
mkdocs inited
This commit is contained in:
12
docs/tgbotapi/introduction/before-any-bot-project.md
Normal file
12
docs/tgbotapi/introduction/before-any-bot-project.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Before any bot project
|
||||
|
||||
There are several places you need to visit for starting work with any Telegram Bot framework on any language:
|
||||
|
||||
* [Bots info introduction](https://core.telegram.org/bots)
|
||||
* [Telegram Bot API reference](https://core.telegram.org/bots/api) (you can skip it, but it could be useful to know some specific cases in Telegram Bot API)
|
||||
|
||||
Anyway, the most important link is [How do I create a bot?](https://core.telegram.org/bots#3-how-do-i-create-a-bot) inside of Telegram Bot API
|
||||
|
||||
## Next steps
|
||||
|
||||
* [Including in your project](including-in-your-project.html)
|
||||
30
docs/tgbotapi/introduction/first-bot.md
Normal file
30
docs/tgbotapi/introduction/first-bot.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# First bot
|
||||
|
||||
> NOTE: **Examples info**
|
||||
> A lot of examples with using of Telegram Bot API you can find in [this github repository](https://github.com/InsanusMokrassar/TelegramBotAPI-examples)
|
||||
|
||||
### The most simple bot
|
||||
|
||||
The most simple bot will just print information about itself. All source code you can find [in this repository](https://github.com/InsanusMokrassar/TelegramBotAPI-examples/tree/master/GetMeBot). Our interest here will be concentrated on the next example part:
|
||||
|
||||
```kotlin
|
||||
suspend fun main(vararg args: String) {
|
||||
val botToken = args.first()
|
||||
val bot = telegramBot(botToken)
|
||||
println(bot.getMe())
|
||||
}
|
||||
```
|
||||
|
||||
So, let's get understanding, about what is going on:
|
||||
|
||||
1. `suspend fun main(vararg args: String)`:
|
||||
* `suspend` required for making of requests inside of this function. For more info you can [open official documentation](https://kotlinlang.org/docs/reference/coroutines/basics.html) for coroutins. In fact, `suspend fun main` is the same that `fun main() = runBlocking {}` from examples
|
||||
2. `val botToken = args.first()`: here we are just getting the bot token from first arguments of command line
|
||||
3. `val bot = telegramBot(botToken)` : inside of `bot` will be [RequestsExecutor](https://tgbotapi.inmo.dev/docs/com.github.insanusmokrassar.-telegram-bot-a-p-i.bot/-requests-executor/index.html) object which will be used for all requests in any project with this library
|
||||
4. `println(bot.getMe())`: here happens calling of [getMe](https://tgbotapi.inmo.dev/docs/com.github.insanusmokrassar.-telegram-bot-a-p-i.extensions.api.bot/get-me.html) extension
|
||||
|
||||
As a result, we will see in the command line something like
|
||||
|
||||
```shell
|
||||
ExtendedBot(id=ChatId(chatId=123456789), username=Username(username=@first_test_ee17e8_bot), firstName=Your bot name, lastName=, canJoinGroups=false, canReadAllGroupMessages=false, supportsInlineQueries=false)
|
||||
```
|
||||
154
docs/tgbotapi/introduction/including-in-your-project.md
Normal file
154
docs/tgbotapi/introduction/including-in-your-project.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# Including in your project
|
||||
|
||||
There are three projects:
|
||||
|
||||
* `TelegramBotAPI Core` - project with base for all working with Telegram Bot API
|
||||
* `TelegramBotAPI API Extensions` - extension of `TelegramBotAPI` with functions for more comfortable work with Telegram Bot API
|
||||
* `TelegramBotAPI Utils Extensions` - extension of `TelegramBotAPI` with functions for extending of different things like retrieving of updates
|
||||
|
||||
> NOTE: **TelegramBotAPI**
|
||||
>
|
||||
> 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
|
||||
|
||||
> NOTE: **Examples**
|
||||
>
|
||||
> You can find full examples info in [this repository](https://github.com/InsanusMokrassar/TelegramBotAPI-examples/). 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](proxy-setup) part
|
||||
|
||||
### Notice about repository
|
||||
|
||||
To use this library, you will need to include `Maven Central` repository in your project
|
||||
|
||||
###### build.gradle
|
||||
|
||||
```groovy
|
||||
mavenCentral()
|
||||
```
|
||||
|
||||
###### pom.xml
|
||||
|
||||
```xml
|
||||
<repository>
|
||||
<id>central</id>
|
||||
<name>mavenCentral</name>
|
||||
<url>https://repo1.maven.org/maven2</url>
|
||||
</repository>
|
||||
```
|
||||
|
||||
###### Dev channel
|
||||
|
||||
Besides, there is [developer versions repo](https://git.inmo.dev/InsanusMokrassar/-/packages/maven/dev.inmo-tgbotapi). To use it in your project, add the repo in `repositories` section:
|
||||
|
||||
<details><summary>Gradle</summary>
|
||||
|
||||
```groovy
|
||||
maven {
|
||||
url "https://git.inmo.dev/api/packages/InsanusMokrassar/maven"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>Maven</summary>
|
||||
|
||||
```xml
|
||||
<repository>
|
||||
<id>dev.inmo</id>
|
||||
<name>InmoDev</name>
|
||||
<url>https://git.inmo.dev/api/packages/InsanusMokrassar/maven</url>
|
||||
</repository>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### TelegramBotAPI
|
||||
|
||||
As `tgbotapi_version` variable in next snippets will be used variable with next last published version:
|
||||
|
||||
[](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi)
|
||||
|
||||
###### build.gradle
|
||||
|
||||
```groovy
|
||||
implementation "dev.inmo:tgbotapi:$tgbotapi_version"
|
||||
```
|
||||
|
||||
###### pom.xml
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>dev.inmo</groupId>
|
||||
<artifactId>tgbotapi</artifactId>
|
||||
<version>${tgbotapi_version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### TelegramBotAPI Core
|
||||
|
||||
As `tgbotapi_version` variable in next snippets will be used variable with next last published version:
|
||||
|
||||
[](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.core)
|
||||
|
||||
###### build.gradle
|
||||
|
||||
```groovy
|
||||
implementation "dev.inmo:tgbotapi.core:$tgbotapi_version"
|
||||
```
|
||||
|
||||
###### pom.xml
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>dev.inmo</groupId>
|
||||
<artifactId>tgbotapi.core</artifactId>
|
||||
<version>${tgbotapi_version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### TelegramBotAPI API Extensions
|
||||
|
||||
As `tgbotapi_version` variable in next snippets will be used variable with next last published version:
|
||||
|
||||
[](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.api)
|
||||
|
||||
###### build.gradle
|
||||
|
||||
```groovy
|
||||
implementation "dev.inmo:tgbotapi.api:$tgbotapi_version"
|
||||
```
|
||||
|
||||
###### pom.xml
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>dev.inmo</groupId>
|
||||
<artifactId>tgbotapi.api</artifactId>
|
||||
<version>${tgbotapi_version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### TelegramBotAPI Utils Extensions
|
||||
|
||||
As `tgbotapi_version` variable in next snippets will be used variable with next last published version:
|
||||
|
||||
[](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.utils)
|
||||
|
||||
###### build.gradle
|
||||
|
||||
```groovy
|
||||
implementation "dev.inmo:tgbotapi.utils:$tgbotapi_version"
|
||||
```
|
||||
|
||||
###### pom.xml
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>dev.inmo</groupId>
|
||||
<artifactId>tgbotapi.utils</artifactId>
|
||||
<version>${tgbotapi_version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
* [Proxy setup](proxy-setup.html)
|
||||
* [First bot](first-bot.html)
|
||||
59
docs/tgbotapi/introduction/proxy-setup.md
Normal file
59
docs/tgbotapi/introduction/proxy-setup.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Proxy setup
|
||||
|
||||
In some locations Telegram Bots API urls will be unavailable. In this case all examples will just throw exception like:
|
||||
|
||||
```bash
|
||||
Exception in thread "main" java.net.ConnectException: Connection refused
|
||||
at sun.nio.ch.SocketChannelImpl.checkConnect(Native Method)
|
||||
at sun.nio.ch.SocketChannelImpl.finishConnect(SocketChannelImpl.java:717)
|
||||
at io.ktor.network.sockets.SocketImpl.connect$ktor_network(SocketImpl.kt:36)
|
||||
at io.ktor.network.sockets.SocketImpl$connect$1.invokeSuspend(SocketImpl.kt)
|
||||
at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
|
||||
at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:56)
|
||||
at kotlinx.coroutines.scheduling.CoroutineScheduler.runSafely(CoroutineScheduler.kt:571)
|
||||
at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.executeTask(CoroutineScheduler.kt:738)
|
||||
at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.runWorker(CoroutineScheduler.kt:678)
|
||||
at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.run(CoroutineScheduler.kt:665)
|
||||
|
||||
Process finished with exit code 1
|
||||
```
|
||||
|
||||
There are several ways to solve this problem:
|
||||
|
||||
* Built-in proxy config (will require some socks or http proxy server)
|
||||
* System-configured VPN or proxy
|
||||
* Your own Bot API Server
|
||||
|
||||
### Using Ktor Client built-in proxy
|
||||
|
||||
First of all, you will need to use one more library:
|
||||
|
||||
**build.gradle**:
|
||||
|
||||
```groovy
|
||||
implementation "io.ktor:ktor-client-okhttp:2.0.1"
|
||||
```
|
||||
|
||||
> NOTE: **Dependency note**
|
||||
> In the snippet above was used version `2.0.1` which is actual for `TelegramBotAPI` at the moment of filling this documentation (`May 22 2022`, `TelegramBotAPI` version `2.0.0`) and you can update version of this dependency in case if it is outdated.
|
||||
|
||||
For configuring proxy for your bot inside your program, you can use next snippet:
|
||||
|
||||
```kotlin
|
||||
val botToken = "HERE MUST BE YOUR TOKEN"
|
||||
val bot = telegramBot(botToken) {
|
||||
ktorClientEngineFactory = OkHttp
|
||||
proxy = ProxyBuilder.socks("127.0.0.1", 1080)
|
||||
}
|
||||
```
|
||||
|
||||
Explanation line by line:
|
||||
|
||||
1. `val botToken = "HERE MUST BE YOUR TOKEN"` - here we are just creating variable `botToken`
|
||||
2. `val bot = telegramBot(botToken) {` - start creating bot
|
||||
3. `ktorClientEngineFactory = OkHttp` - setting up engine factory of our bot. On the time of documentation filling, `OkHttp` is one of the engines in `Ktor` system which supports socks proxy. More you can read on [Ktor](https://ktor.io) site in subparts about [engines](https://ktor.io/clients/http-client/engines.html#okhttp) and [proxy](https://ktor.io/clients/http-client/features/proxy.html)
|
||||
4. `proxy = ProxyBuilder.socks("127.0.0.1", 1080)` - here we are setting up our proxy. Here was used local server which (as assumed) will connect to server like `shadowsocks`
|
||||
|
||||
## Next steps
|
||||
|
||||
* [First bot](first-bot.html)
|
||||
Reference in New Issue
Block a user