Update kotlin monorepo to v2.4.10

36.0.0

BoostsInfoBot/README.md

@@ -1,9 +1,36 @@
-# UserChatShared
+# BoostsInfoBot
 
-Showing info about boosts
+A long-polling example bot that shows the boosts a user has added to a channel. It demonstrates Telegram's channel-request reply-keyboard button, the resulting `chat_shared` service message, the `getUserChatBoosts` Bot API method, and `chat_boost` updates.
+
+## Behavior
+
+1. Open a private chat with the bot and send `/start` (the command takes no arguments).
+2. The bot replies with a **Click me :)** keyboard button. Pressing it opens Telegram's channel picker. The picker is restricted to channels where the bot is already a member.
+3. After a channel is selected, Telegram sends its identifier to the bot in a `chat_shared` service message. The bot accepts only the response associated with its channel-request button (request ID `1`).
+4. The bot calls `getUserChatBoosts` for the selected channel and the user who selected it. It replies with each boost's added and expiration dates plus the unformatted boost object.
+
+If that user has no boosts in the channel, the bot says so. If Telegram rejects the request or another error occurs while obtaining the boosts, it replies with `Unable to take info about boosts in shared chat`.
+
+Separately, every `chat_boost` update received while the bot is running is printed as an unformatted object to standard output. These updates represent boosts that were added or changed; removed-boost updates are not handled by this example. This console output is produced whether or not debug logging is enabled.
+
+## Telegram setup and permissions
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- Use `/start` in a private chat. Telegram's request-chat keyboard buttons are available only in private chats.
+- Before selecting a channel, add the bot to it and promote it to administrator. The button requires the bot to be a member, but it does not request administrator rights. Telegram requires administrator rights both for `getUserChatBoosts` and for receiving `chat_boost` updates.
+- The query returns only boosts added by the user interacting with the bot, not every boost on the selected channel.
+- The example uses long polling and automatically deletes any existing webhook for the bot token at startup. Do not run another long-polling consumer for the same token at the same time.
 
 ## Launch
 
+From the repository root, pass the bot token as the first application argument:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :BoostsInfoBot:run --args="<BOT_TOKEN>"
+```
+
+An optional second argument, exactly `debug`, routes the library's default KSLog output to standard output:
+
+```bash
+./gradlew :BoostsInfoBot:run --args="<BOT_TOKEN> debug"
 ```

BoostsInfoBot/src/main/kotlin/BoostsInfo.kt

@@ -16,6 +16,17 @@ import dev.inmo.tgbotapi.utils.regular
 import korlibs.time.DateFormat
 import korlibs.time.format
 
+/**
+ * Starts the BoostsInfoBot example using long polling.
+ *
+ * The `/start` command sends a channel-request keyboard button that accepts channels where this bot is already a
+ * member. When Telegram returns the matching `chat_shared` service message, the bot calls [getUserChatBoosts] for
+ * the selected channel and the requesting user, then replies with that user's boosts. Incoming `chat_boost` updates
+ * are also printed to standard output.
+ *
+ * @param args the bot token as the first element and, optionally, `debug` as the second element to format and print
+ * default KSLog messages to standard output
+ */
 suspend fun main(args: Array<String>) {
     val isDebug = args.getOrNull(1) == "debug"
 

BotSubscriptionsBot/README.md

@@ -0,0 +1,77 @@
+# BotSubscriptionsBot
+
+Demonstrates the [`subscription`](https://core.telegram.org/bots/api#update) update added in Telegram Bot API
+10.2. Telegram sends a [`BotSubscriptionUpdated`](https://core.telegram.org/bots/api#botsubscriptionupdated) when a
+user cancels a recurring payment subscription to the bot, re-enables a canceled subscription, or a subscription
+payment fails.
+
+This example only observes subscription changes. It does not create an invoice or start a subscription.
+
+## Behavior
+
+At startup, the bot calls `getMe` and prints its own information. It then receives updates through long polling and
+prints every received update object to standard output.
+
+For each subscription update, the bot demonstrates three tgbotapi interfaces:
+
+- `onBotSubscriptionUpdated` handles `BotSubscriptionUpdated` directly. It prints the user ID, invoice payload, and
+  typed state, then makes a best-effort attempt to notify that user in a private chat. A send failure is logged and
+  does not stop polling.
+- `botSubscriptionUpdatedUpdatesFlow` exposes the underlying `BotSubscriptionUpdatedUpdate`; this example prints its
+  update ID, user ID, and state. Consequently, the same event appears in the typed-handler, subscription-flow, and
+  generic all-update logs.
+- `waitBotSubscriptionUpdated().first()` waits for one matching event in the `/wait_subscription` command handler.
+
+The known tgbotapi states are `Active`, `Canceled`, and `Failed`. Unknown state strings are preserved as `Unknown`, so
+the example remains compatible if Telegram adds another state.
+
+## Command
+
+- `/wait_subscription` — a standalone command with no arguments. It replies that it is waiting, then waits without a
+  timeout for the next subscription update and replies in the command's chat with that update's state and invoice
+  payload. The update is not restricted to the command sender, so this unprotected diagnostic command should not be
+  copied into a production bot as-is.
+
+There is no `/start` handler and the bot ignores other commands apart from printing their received update objects.
+
+## Setup
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Use a complete payment implementation for that same bot to create a recurring Telegram Stars (`XTR`) invoice link
+   with [`createInvoiceLink`](https://core.telegram.org/bots/api#createinvoicelink) and a `subscription_period`
+   (currently 2,592,000 seconds, or 30 days), then let a user subscribe. This example has neither an invoice creator nor
+   a `pre_checkout_query` handler, so it cannot establish a new subscription by itself; it is intended to observe state
+   changes for subscriptions created through that payment flow.
+3. Have each subscriber start the bot and leave its private chat unblocked if you want the direct status notification
+   to succeed.
+
+No group or channel membership and no administrator permissions are required for bot payment subscriptions. If you
+run `/wait_subscription` in a group, the bot only needs to receive the command and be allowed to send its replies.
+
+These events concern recurring payments toward the bot. They are different from paid channel subscription invite
+links.
+
+## Arguments
+
+The bot token is required and must be the first argument. The remaining optional flags are exact, case-sensitive
+strings and can be supplied in either order:
+
+| Argument | Effect |
+| --- | --- |
+| `BOT_TOKEN` | Token of the bot to run. |
+| `debug` | Sends tgbotapi/KSLog diagnostic output to standard output. |
+| `testServer` | Uses Telegram's Bot API test environment (`/test`) instead of the production environment. |
+
+## Launch
+
+From the repository root:
+
+```bash
+./gradlew :BotSubscriptionsBot:run --args="BOT_TOKEN"
+```
+
+For example, to enable both optional modes:
+
+```bash
+./gradlew :BotSubscriptionsBot:run --args="BOT_TOKEN debug testServer"
+```

BotSubscriptionsBot/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'kotlin'
+apply plugin: 'application'
+
+mainClassName="BotSubscriptionsBotKt"
+
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    implementation "dev.inmo:tgbotapi:$telegram_bot_api_version"
+}

BotSubscriptionsBot/src/main/kotlin/BotSubscriptionsBot.kt

@@ -0,0 +1,100 @@
+import dev.inmo.kslog.common.KSLog
+import dev.inmo.kslog.common.LogLevel
+import dev.inmo.kslog.common.defaultMessageFormatter
+import dev.inmo.kslog.common.setDefaultKSLog
+import dev.inmo.micro_utils.coroutines.runCatchingLogging
+import dev.inmo.micro_utils.coroutines.subscribeSafelyWithoutExceptions
+import dev.inmo.tgbotapi.extensions.api.bot.getMe
+import dev.inmo.tgbotapi.extensions.api.send.reply
+import dev.inmo.tgbotapi.extensions.api.send.send
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitBotSubscriptionUpdated
+import dev.inmo.tgbotapi.extensions.behaviour_builder.telegramBotWithBehaviourAndLongPolling
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onBotSubscriptionUpdated
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommand
+import dev.inmo.tgbotapi.types.payments.BotSubscriptionUpdated
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.first
+
+/**
+ * Runs a long-polling demonstration of bot payment-subscription updates introduced in Telegram Bot API 10.2.
+ *
+ * Telegram sends a `subscription` update carrying a [BotSubscriptionUpdated] when a user cancels a recurring
+ * payment subscription to the bot, re-enables a canceled subscription, or a subscription payment fails. This
+ * example consumes those updates; it does not create recurring invoices.
+ *
+ * Key concepts demonstrated:
+ * - [onBotSubscriptionUpdated] — trigger whose handler receives a [BotSubscriptionUpdated] (`user`,
+ *   `invoicePayload`, `state`) and makes a best-effort status notification to the subscriber
+ * - [BotSubscriptionUpdated.State] — the typed sealed state: [BotSubscriptionUpdated.State.Active],
+ *   [BotSubscriptionUpdated.State.Canceled], [BotSubscriptionUpdated.State.Failed] (data objects) and the
+ *   [BotSubscriptionUpdated.State.Unknown] value-class fallback for any future state
+ * - `botSubscriptionUpdatedUpdatesFlow` — the raw update flow of
+ *   [dev.inmo.tgbotapi.types.update.BotSubscriptionUpdatedUpdate] (available directly because a
+ *   BehaviourContext is a `FlowsUpdatesFilter`); each emission's payload is its `data`
+ * - [waitBotSubscriptionUpdated] — expectation returning a flow of [BotSubscriptionUpdated]; the
+ *   `/wait_subscription` handler takes its next value without a timeout and replies in the command's chat
+ *
+ * The first command-line argument is always treated as the bot token. Later arguments equal to `debug` and
+ * `testServer` enable console diagnostic logging and Telegram's Bot API test environment, respectively.
+ *
+ * @param args bot token followed by optional, case-sensitive `debug` and `testServer` flags
+ */
+suspend fun main(vararg args: String) {
+    val botToken = args.first()
+    val isDebug = args.any { it == "debug" }
+    val isTestServer = args.any { it == "testServer" }
+
+    if (isDebug) {
+        setDefaultKSLog(
+            KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
+                println(defaultMessageFormatter(level, tag, message, throwable))
+            }
+        )
+    }
+
+    telegramBotWithBehaviourAndLongPolling(
+        botToken,
+        CoroutineScope(Dispatchers.IO),
+        testServer = isTestServer,
+    ) {
+        val me = getMe()
+        println("Bot info: $me")
+
+        // subscription update: react to the typed BotSubscriptionUpdated.State
+        onBotSubscriptionUpdated { update ->
+            val user = update.user
+            val payload = update.invoicePayload
+            val stateText = when (val state = update.state) {
+                BotSubscriptionUpdated.State.Active -> "active ✅"
+                BotSubscriptionUpdated.State.Canceled -> "canceled ❌"
+                BotSubscriptionUpdated.State.Failed -> "payment failed ⚠️"
+                // Unknown is a value class carrying the raw state name — future-proof fallback
+                is BotSubscriptionUpdated.State.Unknown -> "unknown (${state.name})"
+            }
+            println("Subscription update from ${user.id}: payload=$payload, state=${update.state.name}")
+
+            // notify the subscriber (only works if they have an open chat with the bot)
+            runCatchingLogging {
+                send(user.id, "Your subscription (payload: $payload) is now: $stateText")
+            }
+        }
+
+        // Raw flow variant of the same updates. BehaviourContext : FlowsUpdatesFilter, so the flow is
+        // available directly; each emission is a BotSubscriptionUpdatedUpdate whose payload is `.data`.
+        botSubscriptionUpdatedUpdatesFlow.subscribeSafelyWithoutExceptions(this) { update ->
+            println("[flow] update ${update.updateId}: user=${update.data.user.id}, state=${update.data.state.name}")
+        }
+
+        // waitBotSubscriptionUpdated expectation: suspend until the next subscription update
+        onCommand("wait_subscription") {
+            reply(it, "Waiting for the next subscription update...")
+            val update = waitBotSubscriptionUpdated().first()
+            reply(it, "Subscription update: state=${update.state.name}, payload=${update.invoicePayload}")
+        }
+
+        allUpdatesFlow.subscribeSafelyWithoutExceptions(this) {
+            println(it)
+        }
+    }.second.join()
+}

BusinessConnectionsBot/README.md

@@ -1,9 +1,77 @@
-# BusinessConnectionBotBot
+# Business Connections Bot
 
-When bot connected or disconnected to the business chat, it will notify this chat
+This example demonstrates how a bot can manage a connected Telegram Business account. It handles business-connection updates, mirrors business messages, exposes inline actions for marking messages as read or deleting them, and exercises account, Stars, gifts, stories, and checklist APIs.
+
+This is a feature demonstration, not a production-ready bot. Several commands change the connected account or transfer its Stars, and the bot keeps connection IDs only in memory.
+
+## Telegram setup and rights
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Enable Business/Secretary Mode for the bot in BotFather. Telegram's name for the setting can vary by client version.
+3. Start this example, then connect the bot to a Telegram Business account and allow it to manage the desired private chats. The account owner should also open a private chat with the bot; all commands below are accepted only there.
+4. Grant the business rights needed by the features you want to try:
+
+| Business right | Used by |
+| --- | --- |
+| Reply/send messages (`can_reply`) | Mirroring and replying to business messages and resending checklists |
+| Read messages (`can_read_messages`) | **Read message** inline button |
+| Delete all messages (`can_delete_all_messages`) | **Delete message** for incoming customer messages |
+| Delete sent messages (`can_delete_sent_messages`) | Deleting messages sent by the bot itself |
+| Edit name (`can_edit_name`) | `/set_business_account_name` |
+| Edit username (`can_edit_username`) | `/set_business_account_username` |
+| Edit bio (`can_edit_bio`) | `/set_business_account_bio` |
+| Edit profile photo (`can_edit_profile_photo`) | Both profile-photo commands |
+| View gifts and Stars (`can_view_gifts_and_stars`) | Balance and gift-list commands |
+| Transfer Stars (`can_transfer_stars`) | `/transfer_business_account_stars` |
+| Manage stories (`can_manage_stories`) | `/post_story` and `/delete_story` |
+
+The account-management methods used here do not require the connected account to have Telegram Premium as of Bot API 9.0. Sending checklists still depends on the account and client being able to create them. Enable Bot-to-Bot Communication Mode in BotFather if you want to exercise the special reply path for a bot that contacts the managed business account.
+
+See Telegram's [business-bot overview](https://core.telegram.org/bots/features#business-mode) and [`BusinessBotRights`](https://core.telegram.org/bots/api#businessbotrights) for the platform rules. The Bot API generally restricts business replies and reads to private chats active in the last 24 hours.
 
 ## Launch
 
+From the repository root, pass the token as the first application argument:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :BusinessConnectionsBot:run --args="<BOT_TOKEN>"
 ```
+
+Pass the literal `debug` as the optional second argument to print verbose library logs:
+
+```bash
+./gradlew :BusinessConnectionsBot:run --args="<BOT_TOKEN> debug"
+```
+
+The bot prints its own `getMe` result, discards updates accumulated before startup, and then starts long polling. Because business connection IDs are cached only in memory, run the bot before creating/enabling the connection. After a restart, disable and re-enable the connection if owner commands do not respond.
+
+## Automatic business update handling
+
+- When a business connection is enabled or disabled, the bot records/removes its IDs and notifies the account owner in their private chat.
+- A text business message starting with `/pin` or `/unpin` pins or unpins the accessible message it replies to.
+- Other new business messages are resent to the sender's chat and receive a short diagnostic reply. Incoming customer messages also produce a notification in the business owner's bot chat with **Read message** and **Delete message** buttons.
+- When the sender is another bot, the example sends a bot-to-bot diagnostic reply and skips the owner notification.
+- Edited business messages are resent with an edit diagnostic. Deleted-business-message updates are reported to the account owner with the affected chat and message IDs.
+- A received checklist is resent to the same chat on behalf of the business account when the connection ID can be resolved.
+
+The inline **Read message** button calls `readBusinessMessage`. **Delete message** calls `deleteBusinessMessages`; for an incoming customer message, this requires the right to delete all managed-chat messages.
+
+## Private-chat commands
+
+These commands must be sent by the connected account owner in their private chat with the bot. Except for `/get_business_account_info`, handlers silently stop when that chat is not associated with an in-memory business connection.
+
+| Command | Behavior |
+| --- | --- |
+| `/get_business_account_info` | Prints the current `BusinessConnection` as formatted JSON, or reports that no connection is known. |
+| `/set_business_account_name <first_name> [last_name]` | Changes the connected account's first name and optional last name. Each name is parsed as one whitespace-separated argument. |
+| `/set_business_account_username <username>` | Changes the account username to the single supplied argument. |
+| `/get_business_account_star_balance` | Prints the account's current Telegram Stars balance. |
+| `/transfer_business_account_stars <count>` | Transfers an integer number of Stars from the business account to the bot. Telegram accepts values from 1 through 10,000; this example leaves range validation to Telegram. |
+| `/get_business_account_gifts` | Fetches every page of owned gifts and prints their Kotlin representations, splitting long output across messages. |
+| `/set_business_account_bio <text>` | Saves the current bio, sets the complete text after the command as the new bio, waits 15 seconds, and attempts to restore the saved value. An empty text clears it temporarily. |
+| `/set_business_account_profile_photo` | Reply to a photo with this command to set it as the main profile photo; after 15 seconds the bot removes that photo. |
+| `/set_business_account_profile_photo_public` | Reply to a photo to set it as the public profile photo; after 15 seconds the bot removes it. |
+| `/post_story` | Reply to a photo, video, or live photo to post it as a six-hour story with a fixed test caption and link area. |
+| `/delete_story` | Reply to a story message to delete that story. Telegram only permits the bot to delete stories it posted for the business account. |
+
+The profile-photo cleanup removes the newly current photo; it does not upload a saved copy of the previous photo. Telegram may promote the previous main photo after removal. Also note that the success text from `/post_story` currently mentions `/remove_story`; the implemented deletion command is `/delete_story`.

BusinessConnectionsBot/src/main/kotlin/BusinessConnectionsBot.kt

@@ -70,6 +70,16 @@ import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.serialization.json.Json
 
+/**
+ * Starts the long-polling Telegram Business API demonstration bot.
+ *
+ * The bot flushes queued updates before registering its handlers and stores business connection IDs only in memory.
+ * Consequently, an already connected account may need to disable and re-enable its connection after a restart before
+ * owner-side commands can resolve that connection.
+ *
+ * @param args the bot token followed optionally by the literal `debug`, which enables verbose library logging
+ * @throws NoSuchElementException when the bot token is missing
+ */
 suspend fun main(args: Array<String>) {
     val botToken = args.first()
     val isDebug = args.getOrNull(1) == "debug"
@@ -519,4 +529,4 @@ suspend fun main(args: Array<String>) {
             )
         }
     }.second.join()
-}
+}

ChatAvatarSetter/README.md

@@ -1,9 +1,44 @@
 # ChatAvatarSetter
 
-This bot will set the chat avatar based on the image sent to bot
+This Kotlin/JVM example changes a chat's avatar to the photo sent in that chat. It receives updates by long
+polling and demonstrates the Telegram Bot API [`setChatPhoto`](https://core.telegram.org/bots/api#setchatphoto)
+method with a multipart file upload.
+
+## Behavior
+
+- There is no command: every photo message received by the bot is a trigger.
+- The bot downloads the photo, uploads it as `sample.jpg`, and uses it as the avatar of the same chat.
+- After a successful update, it replies `Done`. If `setChatPhoto` fails, it logs the exception and replies
+  `Something went wrong (see logs)`.
+- Non-photo messages are ignored. In particular, an image sent as a document is not a photo message.
+
+The implementation does not restrict who may trigger it. In a group or supergroup, any member whose photo
+message reaches the bot can cause an avatar-change attempt.
+
+## Telegram setup and permissions
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Add the bot to the group, supergroup, or channel whose avatar it should manage.
+3. Promote the bot to administrator and grant it the **Change chat info** permission
+   (`can_change_info`). It must also be able to send messages in a group or posts in a channel to deliver its
+   status reply.
+4. Send a photo directly in that chat.
+
+Telegram does not allow `setChatPhoto` to change private-chat photos. The target chat is always taken from the
+incoming photo message, so a photo sent to the bot privately cannot be used to update another chat.
+
+## Arguments
+
+| Position | Argument | Required | Description |
+| --- | --- | --- | --- |
+| 1 | `BOT_TOKEN` | Yes | Bot API token issued by BotFather. |
 
 ## Launch
 
+From the repository root, run:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :ChatAvatarSetter:run --args="<BOT_TOKEN>"
 ```
+
+The process continues polling until it is stopped.

ChatAvatarSetter/src/main/kotlin/ChatAvatarSetter.kt

@@ -10,6 +10,15 @@ import dev.inmo.tgbotapi.requests.abstracts.asMultipartFile
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
+/**
+ * Starts a long-polling bot that uses each incoming photo as the avatar of the chat where it was sent.
+ *
+ * The bot downloads the photo and uploads it with `setChatPhoto`. It replies `Done` when the avatar is updated;
+ * if that API call fails, it logs the exception and replies with an error message. The target must be a
+ * non-private chat where the bot is an administrator allowed to change chat information.
+ *
+ * @param args command-line arguments whose first value is the Bot API token
+ */
 suspend fun main(args: Array<String>) {
     val bot = telegramBot(args.first())
 

ChatManagementBot/README.md

@@ -0,0 +1,48 @@
+# ChatManagementBot
+
+This long-polling example demonstrates chat-management features introduced in Telegram Bot API 10.0. It inspects a member's `can_react_to_messages` permission, includes other bot administrators in an administrator query, deletes reactions, and logs content messages received from other bots.
+
+At startup, the bot prints its name, username, and `canReadAllGroupMessages` value returned by `getMe`. The latter indicates whether Group Privacy Mode is disabled; it does not enable bot-to-bot communication by itself.
+
+## Commands and triggers
+
+| Command or trigger | Behavior |
+| --- | --- |
+| A member becomes restricted or their restrictions change | Prints the member's new `canReactToMessages` value twice: directly from the restricted member and through the `ChatPermissions` interface. |
+| `/retrieveRights` | Reply to a user-authored message. The bot calls `getChatMember` for that user and replies with their `canReactToMessages` value. It reports `null` when the returned member state is not restricted. |
+| `/admins` | In a group, supergroup, or channel, lists the chat administrators. It passes `retrieveOtherBots = true`, the library equivalent of Telegram's `return_bots = true`, so other bot administrators are included. |
+| `/deleteReaction` | Reply to a user-authored message in a group or supergroup. Removes that user's reaction from the replied-to message. |
+| `/deleteAllReactions` | Reply to a user-authored message in a group or supergroup. Removes up to 10,000 recent reactions made by that user in the current chat. |
+| A content message from another bot arrives | Prints the sender and content to standard output; messages from this bot itself are ignored. |
+
+No command reads positional arguments. The commands that operate on a user take that user from the replied-to message. Command failures from Telegram, including missing permissions, are left to the library's normal error handling.
+
+This is an API example, not a production moderation bot: it does not check whether the person invoking a reaction-deletion command is an administrator.
+
+## Telegram setup and permissions
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Add the bot to the group or supergroup used for the examples and promote it to administrator. Telegram only sends `chat_member` updates about other members to administrators, and `getChatMember` is only guaranteed to work for other users when the bot is an administrator.
+3. Grant the bot the **Delete messages** (`can_delete_messages`) administrator right to use either reaction-deletion command.
+4. To exercise the other-bot message handler, enable **Bot-to-Bot Communication Mode** for the receiving bot in @BotFather. For ordinary messages that are neither an addressed command nor a direct reply, the receiving bot must also be a group administrator and have **Group Privacy Mode** disabled. Re-add the bot after changing Group Privacy Mode so the change takes effect.
+
+See Telegram's documentation for [`chat_member` updates and chat-management methods](https://core.telegram.org/bots/api) and [bot-to-bot communication](https://core.telegram.org/api/bots%2Fbot-to-bot).
+
+## Launch
+
+From the repository root, run:
+
+```bash
+./gradlew :ChatManagementBot:run --args="<BOT_TOKEN> [debug] [testServer]"
+```
+
+The bot token must be the first argument. The optional, case-sensitive flags may follow it in either order:
+
+- `debug` sends the library's logging to standard output.
+- `testServer` uses Telegram's Bot API test environment.
+
+For example:
+
+```bash
+./gradlew :ChatManagementBot:run --args="123456:ABCDEF debug"
+```

ChatManagementBot/src/main/kotlin/ChatManagementBot.kt

@@ -27,27 +27,16 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * This bot demonstrates Chat Management API features added in Bot API 9.x:
+ * Runs a long-polling demonstration of the chat-management features introduced in Telegram Bot API 10.0.
  *
- * 1. `can_react_to_messages` field in `ChatMemberRestricted` — printed when a member's
- *    restrictions are changed (requires the bot to be an admin in the group).
- *    `RestrictedMemberChatMember` also implements `ChatPermissions`, so the same field
- *    covers both `ChatMemberRestricted` and `ChatPermissions` from the spec.
+ * The bot logs changes to a restricted member's `canReactToMessages` permission, exposes commands for querying
+ * member rights and administrators, removes a user's reactions, and logs content messages received from other
+ * bots. Reaction deletion requires the bot's `can_delete_messages` administrator right. Receiving unrestricted
+ * bot-authored group messages additionally requires Bot-to-Bot Communication Mode, administrator status, and
+ * disabled Group Privacy Mode; `canReadAllGroupMessages` only reports the last of those settings.
  *
- * 2. `return_bots` in `getChatAdministrators` — `/admins` command lists all admins
- *    including other bots (retrieveOtherBots = true).
- *
- * 3. `deleteAllMessageReactions` — `/deleteallreactions` in reply to a message removes
- *    all reactions that the replied message's author has left across the entire chat.
- *
- * 4. `deleteMessageReaction` — `/deletereaction` in reply to a message removes the
- *    reaction the replied message's author placed on that specific message.
- *
- * 5. Seeing messages from other bots in groups — demonstrated via `canReadAllGroupMessages`
- *    from `getMe()`. When true (privacy mode off), the bot receives messages from other bots.
- *    All such messages are logged.
- *
- * Usage: pass the bot token as the first argument. Optional: `debug`, `testServer`.
+ * @param args the bot token followed by optional, case-sensitive `debug` and `testServer` flags. `debug` routes
+ * library logs to standard output; `testServer` selects Telegram's Bot API test environment.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
@@ -70,8 +59,8 @@ suspend fun main(vararg args: String) {
         val me = getMe()
         println("Bot: ${me.firstName} (@${me.username?.username})")
 
-        // Feature 5: canReadAllGroupMessages (can_read_all_group_messages) from getMe()
-        // When true, the bot receives messages from other bots in groups (privacy mode off)
+        // canReadAllGroupMessages (can_read_all_group_messages) reports whether Group Privacy Mode is disabled.
+        // Bot-to-bot delivery has additional requirements described in the entry-point KDoc and README.
         println("canReadAllGroupMessages: ${me.canReadAllGroupMessages}")
 
         // Feature 1: can_react_to_messages in ChatMemberRestricted and ChatPermissions
@@ -136,7 +125,7 @@ suspend fun main(vararg args: String) {
         }
 
         // Feature 3: deleteAllMessageReactions
-        // Deletes all reactions that the replied message's author has left in this chat
+        // Deletes up to 10,000 recent reactions that the replied message's author has left in this chat
         onCommand("deleteAllReactions") { message ->
             val replied = message.replyTo?.fromUserMessageOrNull() ?: run {
                 reply(message) { +"Reply to a message to clear all reactions of that user in this chat" }
@@ -147,8 +136,7 @@ suspend fun main(vararg args: String) {
         }
 
         // Feature 5: messages from other bots in groups
-        // Bots with canReadAllGroupMessages=true (privacy mode off) receive messages from other bots.
-        // This handler logs all such messages to demonstrate the feature.
+        // This handler logs bot-authored content messages that Telegram delivers to this bot.
         onContentMessage(
             initialFilter = { msg ->
                 val user = msg.fromUserMessageOrNull()?.user

ChecklistsBot/README.md

@@ -0,0 +1,75 @@
+# ChecklistsBot
+
+This example shows how to receive Telegram checklist messages and checklist service events with
+the TelegramBotAPI behaviour builder. It mirrors each checklist as a formatted text reply; it does
+not create or edit checklists and stores no state.
+
+## Behaviour
+
+The bot uses long polling and installs these handlers:
+
+| Incoming update | Response |
+| --- | --- |
+| A message containing a checklist | Replies to that message with the checklist's current contents. |
+| Tasks marked as done or not done | Replies to the checklist-status service message with the full current checklist. If at least one task was newly marked done, the reply includes the first such task's ID as `checklist_task_id`; an event containing only newly reopened tasks gets a normal message-level reply. |
+| Tasks added to a checklist | Replies to the original checklist and targets the first newly added task with `checklist_task_id`, then includes the full current checklist. |
+
+The text snapshot preserves the title and task text entities. Each task is rendered on its own line
+as `• [x] task` when it has a completion date or `• [ ] task` otherwise; the marker is formatted as
+code and the task text as bold.
+
+There are no bot commands. On startup the bot prints the result of `getMe`, and it prints every raw
+update it receives. The optional `debug` flag additionally sends TelegramBotAPI diagnostic logs to
+standard output.
+
+## Telegram setup
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Start the example, open a private chat with the bot, and send it a checklist. Telegram Premium is
+   currently required to create a checklist in Telegram clients. Use the checklist's own options if
+   other participants should be allowed to add tasks or change their completion state.
+3. For group testing, ensure the bot may send messages and can receive the original checklist.
+   Ordinary checklist messages are hidden by the default Group Privacy Mode, so make the bot a group
+   administrator or disable privacy with BotFather and re-add the bot to the group.
+
+No Telegram Business connection or business-bot right is required: the example only receives
+checklists and sends ordinary text replies. Telegram restricts the `sendChecklist` Bot API method,
+which this example does not use, to connected business accounts.
+
+## Run
+
+From the repository root:
+
+```bash
+./gradlew :ChecklistsBot:run --args="<BOT_TOKEN>"
+```
+
+The token must be first. The remaining optional flags are exact, case-sensitive strings and may be
+supplied in either order:
+
+| Argument | Required | Meaning |
+| --- | --- | --- |
+| `<BOT_TOKEN>` | Yes | Bot token; it must be the first argument. |
+| `debug` | No | Enables verbose TelegramBotAPI logging on standard output. |
+| `testServer` | No | Uses Telegram's Bot API test environment (`/test`) instead of production. |
+
+For example:
+
+```bash
+./gradlew :ChecklistsBot:run --args="<BOT_TOKEN> debug testServer"
+```
+
+Do not run another webhook or long-polling consumer with the same token while this example is
+running.
+
+## API concepts demonstrated
+
+- `onChecklistContent` for checklist content messages.
+- `onChecklistTasksDone` for service messages that contain both completed and reopened task IDs.
+- `onChecklistTasksAdded` for task-addition service messages.
+- Entity-aware output with `buildEntities`, `code`, and `bold`.
+- Replies to a specific checklist item through `checklist_task_id`.
+
+See Telegram's [Checklist and ChecklistTask objects](https://core.telegram.org/bots/api#checklist)
+and [checklist launch announcement](https://telegram.org/blog/checklists-suggested-posts#checklists)
+for the underlying platform behaviour.

ChecklistsBot/src/main/kotlin/ChecklistsBot.kt

@@ -46,6 +46,17 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 
+/**
+ * Starts a long-polling bot that renders incoming checklists as formatted text and reports
+ * checklist task additions and completion-state changes with task-aware replies.
+ *
+ * The first argument is the required bot token. The optional, case-sensitive `debug` and
+ * `testServer` arguments enable verbose library logging and Telegram's Bot API test environment,
+ * respectively. The bot identity and every received update are printed to standard output in all
+ * modes.
+ *
+ * @param args bot token followed by optional `debug` and `testServer` flags
+ */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
 
@@ -65,7 +76,6 @@ suspend fun main(vararg args: String) {
         CoroutineScope(Dispatchers.Default),
         testServer = isTestServer,
     ) {
-        // start here!!
         val me = getMe()
         println(me)
 

CommunitiesBot/README.md

@@ -0,0 +1,50 @@
+# CommunitiesBot
+
+This long-polling example demonstrates Communities support introduced in Telegram Bot API 10.2: typed service events when a chat joins or leaves a community, and inspection of a chat's current community.
+
+## Behavior, commands, and triggers
+
+At startup, the bot calls `getMe` and prints its bot information. It also prints every received update to standard output.
+
+| Command or trigger | Behavior |
+| --- | --- |
+| `community_chat_added` service message | `onCommunityChatAdded` logs the chat and community name/ID, sends a join notice, then calls `getChat` and logs its nullable `community`. |
+| `community_chat_removed` service message | `onCommunityChatRemoved` logs the chat and sends a leave notice. This event is fieldless, so it has no former-community details. |
+| `/community` | Calls `getChat` and replies with the current community name/ID, or says the chat is not in a community. |
+| `/wait_community_added` | Waits without a timeout for the next added event in the command's chat, then replies with the community name/ID. |
+| `/wait_community_removed` | Waits without a timeout for the next removed event in the command's chat, then replies with the chat ID. Its initial waiting reply currently says "added." |
+
+Commands use no positional arguments; other commands only appear in the generic update log. Each wait first sends a waiting reply, filters events with `sameChat`, and takes the first match.
+
+## API concepts
+
+- `CommunityChatAdded` carries a `Community` with a `CommunityId` and name; `CommunityChatRemoved` carries no fields.
+- `onCommunityChatAdded` and `onCommunityChatRemoved` provide typed handlers for the service events.
+- `getChat(...).community` exposes the nullable community on `ExtendedChat` without a subtype cast.
+- `waitCommunityChatAddedEventsMessages` and `waitCommunityChatRemovedEventsMessages` expose typed event-message flows.
+
+## Telegram setup and permissions
+
+1. Create a bot with BotFather and obtain its token.
+2. Add it to the target chat before changing that chat's community membership if you want to observe both service events.
+3. Allow it to send messages so notifications and command replies succeed.
+
+The bot does not create or modify communities. It calls no administrator-only method and does not inspect arbitrary user messages, so it needs neither administrator rights nor disabled Group Privacy Mode. The user changing community membership still needs the appropriate Telegram rights. API failures are left to the library's normal error handling.
+
+## Arguments
+
+The token is required as the first argument. Optional flags are exact and case-sensitive, may follow in either order, and unknown extra arguments are ignored.
+
+| Argument | Effect |
+| --- | --- |
+| `BOT_TOKEN` | Bot token; omitting it fails before polling starts. |
+| `debug` | Sends tgbotapi/KSLog diagnostics to standard output. |
+| `testServer` | Uses Telegram's Bot API test environment. |
+
+## Launch
+
+From the repository root:
+
+```bash
+./gradlew :CommunitiesBot:run --args="BOT_TOKEN"
+```

CommunitiesBot/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'kotlin'
+apply plugin: 'application'
+
+mainClassName="CommunitiesBotKt"
+
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    implementation "dev.inmo:tgbotapi:$telegram_bot_api_version"
+}

CommunitiesBot/src/main/kotlin/CommunitiesBot.kt

@@ -0,0 +1,106 @@
+import dev.inmo.kslog.common.KSLog
+import dev.inmo.kslog.common.LogLevel
+import dev.inmo.kslog.common.defaultMessageFormatter
+import dev.inmo.kslog.common.setDefaultKSLog
+import dev.inmo.micro_utils.coroutines.subscribeSafelyWithoutExceptions
+import dev.inmo.tgbotapi.extensions.api.bot.getMe
+import dev.inmo.tgbotapi.extensions.api.chat.get.getChat
+import dev.inmo.tgbotapi.extensions.api.send.reply
+import dev.inmo.tgbotapi.extensions.api.send.send
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatAdded
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatAddedEventsMessages
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatRemoved
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatRemovedEventsMessages
+import dev.inmo.tgbotapi.extensions.behaviour_builder.telegramBotWithBehaviourAndLongPolling
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommand
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommunityChatAdded
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommunityChatRemoved
+import dev.inmo.tgbotapi.extensions.utils.extensions.sameChat
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.first
+
+/**
+ * Starts a long-polling bot that demonstrates Telegram Communities.
+ *
+ * [onCommunityChatAdded] receives the joined [dev.inmo.tgbotapi.types.communities.Community], while
+ * [onCommunityChatRemoved] receives a fieldless removal event. `/community` reads
+ * [dev.inmo.tgbotapi.types.chat.ExtendedChat.community] with [getChat]. The two wait commands use
+ * [waitCommunityChatAddedEventsMessages] and [waitCommunityChatRemovedEventsMessages] to take the first same-chat
+ * event without a timeout. The bot prints its [getMe] result and every received update.
+ *
+ * @param args the bot token followed by the optional, case-sensitive `debug` and `testServer` flags; unknown trailing
+ * arguments are ignored
+ * @throws NoSuchElementException when the required bot token is absent
+ */
+suspend fun main(vararg args: String) {
+    val botToken = args.first()
+    val isDebug = args.any { it == "debug" }
+    val isTestServer = args.any { it == "testServer" }
+
+    if (isDebug) {
+        setDefaultKSLog(
+            KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
+                println(defaultMessageFormatter(level, tag, message, throwable))
+            }
+        )
+    }
+
+    telegramBotWithBehaviourAndLongPolling(
+        botToken,
+        CoroutineScope(Dispatchers.IO),
+        testServer = isTestServer,
+    ) {
+        val me = getMe()
+        println("Bot info: $me")
+
+        // community_chat_added: the chat was added to a community
+        onCommunityChatAdded { message ->
+            val community = message.chatEvent.community
+            println("Chat ${message.chat.id} was added to community '${community.name}' (id=${community.id.long})")
+            send(message.chat.id, "This chat has joined the community: ${community.name}")
+
+            // community is exposed on ExtendedChat itself (ChatFullInfo.community) — no cast needed
+            val extended = getChat(message.chat.id)
+            println("getChat().community = ${extended.community?.name} / ${extended.community?.id?.long}")
+        }
+
+        // community_chat_removed: a fieldless event — the chat left its community
+        onCommunityChatRemoved { message ->
+            println("Chat ${message.chat.id} was removed from its community")
+            send(message.chat.id, "This chat has left its community")
+        }
+
+        // Inspect the current chat's community on demand
+        onCommand("community") {
+            val community = getChat(it.chat.id).community
+            reply(
+                it,
+                if (community != null) {
+                    "Community: ${community.name} (id=${community.id.long})"
+                } else {
+                    "This chat is not part of any community"
+                }
+            )
+        }
+
+        // Suspend until the next community-added event message from this chat.
+        onCommand("wait_community_added") { origin ->
+            reply(origin, "Waiting for this chat to be added to a community...")
+            val event = waitCommunityChatAddedEventsMessages().filter { it.sameChat(origin) }.first().chatEvent
+            reply(origin, "Chat added to community: ${event.community.name} (id=${event.community.id.long})")
+        }
+
+        // Suspend until the next community-removed event message from this chat.
+        onCommand("wait_community_removed") { origin ->
+            reply(origin, "Waiting for this chat to be added to a community...")
+            waitCommunityChatRemovedEventsMessages().filter { it.sameChat(origin) }.first()
+            reply(origin, "Chat removed from its community (${origin.chat.id})")
+        }
+
+        allUpdatesFlow.subscribeSafelyWithoutExceptions(this) {
+            println(it)
+        }
+    }.second.join()
+}

CustomBot/README.md

@@ -1,9 +1,48 @@
 # CustomBot
 
-This bot basically have no any useful behaviour, but you may customize it as a playground
+CustomBot is a diagnostics-heavy playground for experimenting with TelegramBotAPI's behaviour
+builder. It uses long polling, prints the result of `getMe` at startup, logs every received update,
+and prints every Bot API request and result. It is intended as an example to modify, not as a
+production bot.
 
-## Launch
+## Commands and updates
+
+| Command or update | Behaviour |
+| --- | --- |
+| `/start` | Prints the captured update, context data, and `getChat` result. It fetches profile audios for the current private-chat ID in pages of two, replying with one audio or a two-audio playlist for each non-empty page. |
+| `/additional_command` | Demonstrates handler-specific subcontext initialization by storing the command message and printing it with the captured update. It sends no reply. |
+| `/getMyStarBalance` | Replies with the bot's current Telegram Stars balance. |
+| Channel direct-messages configuration changed | Prints the event to standard output. |
+
+The commands take no arguments. Use `/start` in a private chat: the example deliberately uses the
+chat ID as the user ID for `getUserProfileAudios`. No administrator rights are needed for the
+private-chat commands. The channel event is only observable when Telegram delivers that update for
+a channel in which the bot participates.
+
+## Run
+
+Create a bot, obtain its token, and run this command from the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :CustomBot:run --args="<BOT_TOKEN>"
 ```
+
+The token must be the first application argument. Two optional, case-sensitive flags may follow in
+either order:
+
+- `debug` enables TelegramBotAPI library logs on standard output. The bot's explicit request,
+  result, and update logging is active even without this flag.
+- `testServer` selects Telegram's Bot API test environment instead of production.
+
+For example:
+
+```bash
+./gradlew :CustomBot:run --args="<BOT_TOKEN> debug testServer"
+```
+
+## API concepts demonstrated
+
+- Global and handler-specific `BehaviourContextData` initialization.
+- Request/result middleware and subscription to `allUpdatesFlow`.
+- Paginated `getUserProfileAudios` calls and audio/media-group replies.
+- Command and channel-direct-message event handlers.

CustomBot/src/main/kotlin/CustomBot.kt

@@ -36,7 +36,13 @@ private var BehaviourContextData.commonMessage: ChatContentMessage<*>?
     set(value) = set("commonMessage", value)
 
 /**
- * This place can be the playground for your code.
+ * Runs a diagnostics-oriented TelegramBotAPI playground using long polling.
+ *
+ * The bot logs every update and Bot API result, demonstrates global and handler-specific context
+ * initialization, exposes commands for profile audios and the bot's Star balance, and observes
+ * channel direct-messages configuration changes.
+ *
+ * @param args bot token followed by optional, case-sensitive `debug` and `testServer` flags
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

DeepLinksBot/README.md

@@ -1,9 +1,37 @@
 # DeepLinksBot
 
-This bot will send you deeplink to this bot when you send some text message and react on the `start` button
+An example long-polling bot that creates deep links to itself and demonstrates two
+ways to consume their payloads with the TelegramBotAPI behaviour builder.
 
-## Launch
+## Behavior
+
+- On startup, the bot fetches and prints its own account details. It stops if the
+  account has no username, because a username is required to build a deep link.
+- `/start` without arguments returns a short usage hint.
+- A text message containing no bot-command entity is used as the payload of a new
+  deep link, which the bot returns to the sender.
+- A `/start <payload>` deep link is observed by both an `onDeepLink` trigger and a
+  `waitDeepLinks` waiter. Their replies identify which API received the payload.
+- The waiter also prints the registered command handlers for demonstration and
+  debugging purposes.
+
+Messages containing a bot command are excluded from link generation. The bot has
+no persistence and runs until the process is stopped.
+
+## Requirements
+
+- A Telegram bot token supplied as the first command-line argument.
+- A username configured for the bot account.
+- No special administrator permissions; the bot only needs to receive messages
+  and send replies in the chat where it is used.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :DeepLinksBot:run --args="BOT_TOKEN"
 ```
+
+Replace `BOT_TOKEN` with the token for the bot. Additional command-line arguments
+are ignored. Omitting the token causes startup to fail before polling begins.

DeepLinksBot/src/main/kotlin/DeepLinksBot.kt

@@ -10,7 +10,14 @@ import dev.inmo.tgbotapi.extensions.utils.formatting.makeTelegramDeepLink
 import dev.inmo.tgbotapi.types.message.textsources.BotCommandTextSource
 
 /**
- * This bot will send you deeplink to this bot when you send some text message and react on the `start` button
+ * Runs a long-polling bot that turns non-command text into a deep link to itself
+ * and acknowledges payloads received through `/start`.
+ *
+ * The bot account must have a username so that its deep links can be constructed.
+ *
+ * @param args the bot token as the first argument; any remaining arguments are ignored
+ * @throws NoSuchElementException when no bot token is supplied
+ * @throws IllegalStateException when the bot account has no username
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

DraftsBot/README.md

@@ -1,9 +1,41 @@
-# Drafts bot
+# DraftsBot
 
-The main purpose of this bot is just to answer "Oh, hi, " and add user mention here
+DraftsBot demonstrates streaming a message draft before sending the finished
+message. It receives updates through long polling and uses the same built-in
+Lorem ipsum text for both examples.
 
-## Launch
+## Commands
+
+- `/test_draft_flow` publishes progressively longer 50-character prefixes every
+  500 ms, then sends the complete text as a normal message.
+- `/test_empty_draft` first publishes an empty draft, waits 1.5 seconds, streams
+  the same prefixes, and then sends the complete text.
+
+The bot advertises both commands in Telegram's command menu for all group chats.
+The handlers themselves are not restricted by chat type, so either command can
+also be entered manually in a private chat.
+
+## Setup
+
+1. Obtain a bot token and keep it out of source control.
+2. Start a private chat with the bot, or add it to a group where you want to run
+   the example.
+3. In groups, allow the bot to send messages. No administrator rights are
+   otherwise required by this example.
+
+The first program argument is required and must be the bot token. Omitting it
+causes startup to fail; any later arguments are ignored.
+
+## Run
+
+From the repository root, run:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :DraftsBot:run --args="<BOT_TOKEN>"
 ```
+
+> **Known issue:** `DraftsBot/build.gradle` currently declares `TopicsHandlingKt` as the main class, while this bot's entry point is `DraftsBotKt`. The `run` task cannot start until that Gradle setting is corrected; it is left unchanged by this documentation-only update.
+
+Every received update is printed to standard output. Unhandled polling errors
+are printed with their stack traces, and HTTP request, socket, and connection
+timeouts are each configured to 30 seconds.

DraftsBot/src/main/kotlin/DraftsBot.kt

@@ -37,10 +37,19 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.isActive
 
+/** Sample text streamed as a draft and then sent as the completed message. */
 const val testText = """
     Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.    
 """
 
+/**
+ * Starts DraftsBot with long polling and registers the draft demonstration commands.
+ *
+ * The first element of [args] must be the bot token; subsequent elements are ignored.
+ * This function remains suspended until the polling job completes.
+ *
+ * @throws NoSuchElementException when no bot token is supplied
+ */
 suspend fun main(vararg args: String) {
     telegramBotWithBehaviourAndLongPolling(
         args.first(),

EphemeralMessagesBot/README.md

@@ -0,0 +1,40 @@
+# EphemeralMessagesBot
+
+Demonstrates ephemeral messages: group messages that Telegram shows only to one receiver.
+
+## Behavior
+
+- `/ephemeral` replies with a **Reveal a secret** inline button. The command is registered with Telegram as
+  an ephemeral command.
+- Pressing the button (`reveal` callback data) sends a personal message visible only to the user who
+  pressed it. After three seconds the bot edits the message, then deletes it three seconds later.
+- When the bot receives an ephemeral content message, it sends two ephemeral replies: one through the
+  general `reply` API and one through the explicit `replyToEphemeral` API.
+- Updates and basic bot information are printed to standard output.
+
+## Setup
+
+Create a bot token, keep it secret, and add the bot to a group. The bot must be allowed to send messages
+there; this example does not request or validate group permissions itself. Use a Telegram environment that
+supports ephemeral messages.
+
+## Run
+
+From the repository root, pass the token as the first application argument:
+
+```bash
+./gradlew :EphemeralMessagesBot:run --args="BOT_TOKEN"
+```
+
+Optional, case-sensitive arguments may follow the token:
+
+- `debug` enables formatted library logging on standard output.
+- `testServer` connects the bot to Telegram's test server.
+
+For example:
+
+```bash
+./gradlew :EphemeralMessagesBot:run --args="BOT_TOKEN debug testServer"
+```
+
+The token is required; starting without it fails before polling begins. Stop the bot with `Ctrl+C`.

EphemeralMessagesBot/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'kotlin'
+apply plugin: 'application'
+
+mainClassName="EphemeralMessagesBotKt"
+
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    implementation "dev.inmo:tgbotapi:$telegram_bot_api_version"
+}

EphemeralMessagesBot/src/main/kotlin/EphemeralMessagesBot.kt

@@ -0,0 +1,128 @@
+import dev.inmo.kslog.common.KSLog
+import dev.inmo.kslog.common.LogLevel
+import dev.inmo.kslog.common.defaultMessageFormatter
+import dev.inmo.kslog.common.setDefaultKSLog
+import dev.inmo.micro_utils.coroutines.subscribeSafelyWithoutExceptions
+import dev.inmo.tgbotapi.extensions.api.bot.getMe
+import dev.inmo.tgbotapi.extensions.api.bot.setMyCommands
+import dev.inmo.tgbotapi.extensions.api.deleteEphemeralMessage
+import dev.inmo.tgbotapi.extensions.api.edit.text.editEphemeralMessageText
+import dev.inmo.tgbotapi.extensions.api.send.reply
+import dev.inmo.tgbotapi.extensions.api.send.replyToEphemeral
+import dev.inmo.tgbotapi.extensions.api.send.sendTextMessage
+import dev.inmo.tgbotapi.extensions.behaviour_builder.telegramBotWithBehaviourAndLongPolling
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommand
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onContentMessage
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onMessageDataCallbackQuery
+import dev.inmo.tgbotapi.extensions.utils.types.buttons.dataButton
+import dev.inmo.tgbotapi.extensions.utils.types.buttons.flatInlineKeyboard
+import dev.inmo.tgbotapi.types.BotCommand
+import dev.inmo.tgbotapi.types.ephemeralReplyReceiverUserIdOrNull
+import dev.inmo.tgbotapi.types.message.abstracts.PossiblyEphemeralMessage
+import korlibs.time.seconds
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+
+/**
+ * Runs the ephemeral-messages example bot using long polling.
+ *
+ * `/ephemeral` posts an inline button whose callback sends, edits, and deletes a message visible only to
+ * the user who pressed it. Incoming [PossiblyEphemeralMessage] instances receive both an automatic
+ * ephemeral [reply] and an explicit [replyToEphemeral].
+ *
+ * [args] must start with the bot token. The optional exact values `debug` and `testServer` respectively
+ * enable console logging and select Telegram's test server.
+ *
+ * @throws NoSuchElementException when [args] does not contain a bot token
+ */
+suspend fun main(vararg args: String) {
+    val botToken = args.first()
+    val isDebug = args.any { it == "debug" }
+    val isTestServer = args.any { it == "testServer" }
+
+    if (isDebug) {
+        setDefaultKSLog(
+            KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
+                println(defaultMessageFormatter(level, tag, message, throwable))
+            }
+        )
+    }
+
+    telegramBotWithBehaviourAndLongPolling(
+        botToken,
+        testServer = isTestServer,
+    ) {
+        val me = getMe()
+        println("Bot info: $me")
+
+        // Post (in a group) a message with an inline button. Tapping it triggers an ephemeral reply that is
+        // visible only to the user who tapped.
+        onCommand("ephemeral") {
+            reply(
+                it,
+                "Tap the button — the reply will be ephemeral (visible only to you).",
+                replyMarkup = flatInlineKeyboard {
+                    dataButton("Reveal a secret", "reveal")
+                }
+            )
+        }
+
+        // Send an ephemeral message in response to a callback query. `receiverUserId` + `callbackQueryId`
+        // make the outgoing message ephemeral — Telegram shows it only to the querying user (and this also
+        // serves as the answer to the callback query).
+        onMessageDataCallbackQuery(Regex("reveal")) { query ->
+            val chatId = query.message.chat.id
+            val receiverUserId = query.from.id
+
+            val sent = sendTextMessage(
+                chatId,
+                "🔒 ${query.from.firstName}, here is your personal secret: 42",
+                receiverUserId = receiverUserId,
+                callbackQueryId = query.id,
+            )
+
+            // Only the group-family Common*ContentMessage types implement PossiblyEphemeralMessage, so the
+            // sent ephemeral message exposes its ephemeralMessageId through that interface.
+            val ephemeralMessageId = (sent as? PossiblyEphemeralMessage)?.ephemeralMessageId
+            if (ephemeralMessageId != null) {
+                delay(3.seconds)
+                // editEphemeralMessageText: address the ephemeral message by chatId + receiverUserId + ephemeralMessageId
+                editEphemeralMessageText(chatId, receiverUserId, ephemeralMessageId, "🔓 Revealed: the answer is 42")
+                delay(3.seconds)
+                // deleteEphemeralMessage: same addressing (there is also a PossiblyEphemeralMessage overload)
+                deleteEphemeralMessage(chatId, receiverUserId, ephemeralMessageId)
+            }
+        }
+
+        // Incoming ephemeral messages: detect them via PossiblyEphemeralMessage, then answer them.
+        onContentMessage { message ->
+            val ephemeral = (message as? PossiblyEphemeralMessage)?.takeIf { it.ephemeralMessageId != null }
+                ?: return@onContentMessage
+
+            // reply smart-branch: because `message` is ephemeral, this reply is sent ephemeral to the same
+            // receiver automatically — no ephemeral parameters needed here.
+            reply(message, "Got your ephemeral message — I am replying ephemerally too.")
+
+            // The explicit equivalent, addressing the ephemeral message by hand:
+            val receiverUserId = ephemeral.ephemeralReplyReceiverUserIdOrNull
+            if (receiverUserId != null) {
+                replyToEphemeral(
+                    message.chat.id,
+                    receiverUserId,
+                    ephemeral.ephemeralMessageId!!,
+                    "Explicit ephemeral reply via replyToEphemeral",
+                )
+            }
+        }
+
+        setMyCommands(
+            // isEphemeral marks a command whose response is an ephemeral (personal) message
+            BotCommand("ephemeral", "Post a button that reveals an ephemeral (personal) message", isEphemeral = true),
+        )
+
+        allUpdatesFlow.subscribeSafelyWithoutExceptions(this) {
+            println(it)
+        }
+    }.second.join()
+}

FSMBot/README.md

@@ -1,10 +1,44 @@
-# FSM
+# FSMBot
 
-This bot contains an example of working with FSM included in project
-[MicroUtils](https://github.com/InsanusMokrassar/MicroUtils)
+FSMBot demonstrates the finite-state-machine (FSM) support provided by
+[MicroUtils](https://github.com/InsanusMokrassar/MicroUtils) and TelegramBotAPI's
+behaviour builder.
 
-## Launch
+## Behaviour
+
+1. Send `/start` to begin a conversation chain for the current chat.
+2. The bot asks for content and waits in the same forum topic/thread in which the
+   chain was started.
+3. Each content message is copied back to the chat, then the bot waits again.
+4. Send `/stop` in that topic/thread to end the chain and receive a confirmation.
+
+FSM state is held in memory, so active chains are lost when the process stops.
+Incoming updates and state-handling errors are printed to standard output.
+
+## Commands
+
+- `/start` — start or restart the content-resending chain.
+- `/stop` — stop the active chain while the bot is waiting for content.
+
+The bot does not register its command menu automatically; commands can be typed
+directly or configured separately with BotFather.
+
+## Requirements and permissions
+
+- A bot token obtained from BotFather.
+- A compatible JDK for the repository's Gradle wrapper.
+- Permission to send messages and the content types being copied in the target chat.
+- No administrator rights are required. For use in groups, disable privacy mode if
+  the bot must receive arbitrary non-command messages rather than only commands and
+  other updates Telegram exposes to privacy-enabled bots.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :FSMBot:run --args="<BOT_TOKEN>"
 ```
+
+`BOT_TOKEN` is the required first positional argument. The bot uses long polling;
+no webhook or additional configuration is needed.

FSMBot/src/main/kotlin/SimpleFSMBot.kt

@@ -23,10 +23,25 @@ import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.map
 
+/** State hierarchy for a chat-scoped content-resending conversation. */
 sealed interface BotState : State
+
+/**
+ * Waits for content or a `/stop` command in the thread of [sourceMessage].
+ *
+ * @property context Chat whose FSM chain owns this state.
+ * @property sourceMessage Message that determines the forum topic/thread to observe.
+ */
 data class ExpectContentOrStopState(override val context: IdChatIdentifier, val sourceMessage: ChatContentMessage<TextContent>) : BotState
+
+/** Terminal state that acknowledges the end of the chain in [context]. */
 data class StopState(override val context: IdChatIdentifier) : BotState
 
+/**
+ * Starts the FSM-based resender using the bot token in the first command-line argument.
+ *
+ * The bot runs with long polling until its coroutine is cancelled.
+ */
 suspend fun main(args: Array<String>) {
     val botToken = args.first()
 

FilesLoaderBot/README.md

@@ -1,9 +1,42 @@
 # FilesLoaderBot
 
-This bot will download incoming files
+FilesLoaderBot downloads media received through Telegram, stores it on the local
+filesystem, and sends the downloaded media back to the same chat. It uses long
+polling and logs every received update to standard output.
 
-## Launch
+## Behavior
+
+- `/start` asks the user to send media.
+- Any received photo, animation, live photo, video, sticker, document, audio,
+  voice message, video note, or supported media group is handled.
+- The file is saved under the filename returned by Telegram. On success, the bot
+  replies with the absolute saved path and then uploads the media back to the chat.
+- Media groups are downloaded to temporary files and returned as a media group.
+- Download failures are printed to standard error.
+
+The bot does not restrict users or chats. Run it with a dedicated output directory
+and appropriate filesystem quotas if it is exposed beyond trusted users.
+
+## Setup
+
+Create a bot and provide its token as the first command-line argument. The process
+must have network access and permission to create and write to the output directory.
+The directory is created when absent and defaults to `/tmp/` when omitted.
+
+No Telegram administrator rights are required in a private chat. For group use,
+configure the bot so that it receives the media messages you expect it to process.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN[ optional/folder/path]"
+./gradlew :FilesLoaderBot:run --args='<BOT_TOKEN>'
+./gradlew :FilesLoaderBot:run --args='<BOT_TOKEN> /absolute/output/directory'
 ```
+
+Arguments:
+
+1. `BOT_TOKEN` (required): the Telegram bot token.
+2. `OUTPUT_DIRECTORY` (optional): the local destination directory; defaults to
+   `/tmp/`.

FilesLoaderBot/src/main/kotlin/FilesLoaderBot.kt

@@ -20,7 +20,10 @@ import kotlinx.coroutines.Dispatchers
 import java.io.File
 
 /**
- * This bot will download incoming files
+ * Starts the long-polling media downloader and echo bot.
+ *
+ * [args] must contain the bot token and may contain an output directory as its
+ * second item. The directory is created when necessary and defaults to `/tmp/`.
  */
 suspend fun main(args: Array<String>) {
     val botToken = args.first()

ForwardInfoSenderBot/README.md

@@ -1,9 +1,35 @@
-# ForwarderBot
+# ForwardInfoSenderBot
 
-The main purpose of this bot is just to send info about forwarder when bot receive any update
+This example uses long polling to inspect the forward metadata of every content message
+delivered to the bot and replies with a short description of its source.
 
-## Launch
+## Behavior
+
+There are no bot commands. Send or forward any content message that Telegram delivers to
+the bot. The reply depends on the message's `forwardInfo`:
+
+- messages without forward metadata produce `There is no forward info`;
+- anonymous forwards show the sender signature;
+- user and bot forwards show the sender type, numeric ID, name, and username when present;
+- channel forwards show the channel title, linked when the channel has a public username;
+- supergroup forwards show the group title;
+- messages sent on behalf of a channel show that channel's title.
+
+The response uses Telegram text entities to format identifiers and source names. The bot
+can only report metadata that Telegram includes in the received message.
+
+## Setup and permissions
+
+Obtain a bot token and make sure the bot can receive the messages you want to inspect and
+send replies in that chat. It does not request administrator privileges or use persistent
+storage. Telegram's bot privacy and chat permissions still determine which group messages
+are delivered and whether the reply can be sent.
+
+Run from the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :ForwardInfoSenderBot:run --args="<BOT_TOKEN>"
 ```
+
+The token is the required first application argument. Additional arguments are ignored;
+omitting the token makes startup fail. The process keeps polling until it is stopped.

ForwardInfoSenderBot/src/main/kotlin/ForwardInfoSenderBot.kt

@@ -13,8 +13,11 @@ import dev.inmo.tgbotapi.utils.regular
 import kotlinx.coroutines.*
 
 /**
- * This bot will always return message about forwarder. In cases when sent message was not a forward message it will
- * send suitable message
+ * Starts a long-polling bot that replies to each received content message with its forward-source metadata.
+ *
+ * Messages without forward metadata receive a corresponding fallback response.
+ *
+ * @param args the bot token as the required first element; any remaining elements are ignored
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

GiftsBot/README.md

@@ -0,0 +1,46 @@
+# GiftsBot
+
+Demonstrates the paginated owned-gift APIs by listing gifts for the chat in which the command is received.
+
+## Behavior
+
+At startup the bot prints its `getMe` result, then receives updates through long polling. While handling `/start`, it
+shows a typing action, retrieves every page of gifts, and chooses the request from the command chat type:
+
+- a business chat uses the business connection ID and requests the connected business account's gifts;
+- a private chat requests that user's gifts;
+- a public or unknown chat type requests that chat's gifts.
+
+Regular gifts are shown with their ID, optional text, and Stars cost. Unique gifts are shown with their optional ID,
+name, model, and number. Long results are split into multiple Telegram messages; an empty result produces
+`This chat have no any gifts`.
+
+## Command
+
+- `/start` — lists the owned gifts selected by the current chat type. It must be the only command in the message and
+  takes no arguments.
+
+Other commands and non-command messages are ignored.
+
+## Setup and permissions
+
+1. Create a bot with BotFather and obtain its token.
+2. For private-chat use, have the user start the bot so it can receive `/start` and reply.
+3. For group or channel use, add the bot and allow it to receive the command and send messages in that chat.
+4. For business-chat use, enable the bot's Business/Secretary mode, connect it to the business account, and grant the
+   **View gifts and Stars** (`can_view_gifts_and_stars`) business right.
+
+The example performs no access checks or error recovery, so Telegram API or permission errors end that command
+handler.
+
+## Arguments and launch
+
+The first application argument is the required bot token. Optional, exact, case-sensitive flags may follow in either
+order: `debug` prints KSLog diagnostics to standard output, and `testServer` selects Telegram's Bot API test server.
+Unknown trailing arguments are ignored.
+
+From the repository root:
+
+```bash
+./gradlew :GiftsBot:run --args="<BOT_TOKEN>"
+```

GiftsBot/src/main/kotlin/GiftsBot.kt

@@ -25,6 +25,17 @@ import dev.inmo.tgbotapi.utils.buildEntities
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
+/**
+ * Starts a long-polling bot whose standalone `/start` command lists all owned gifts for the current chat.
+ *
+ * Business chats are queried through their business connection, private chats through their user ID, and public or
+ * unknown chat types through their chat ID. Regular and unique gifts are rendered as formatted text and long results
+ * are split across replies. The bot also prints its [getMe] result at startup.
+ *
+ * @param args the bot token followed by optional, case-sensitive `debug` and `testServer` flags; unknown trailing
+ * arguments are ignored
+ * @throws NoSuchElementException when the required bot token is absent
+ */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
 

GiveawaysBot/README.md

@@ -1,9 +1,43 @@
-# CustomBot
+# GiveawaysBot
 
-Printing giveaways
+A long-polling example that prints giveaway-related Telegram updates to standard output.
 
-## Launch
+## Behavior
+
+At startup, the bot calls `getMe` and prints its own user information. It then prints
+updates matched by these TelegramBotAPI handlers:
+
+- `onGiveawayCreated` — a giveaway was created;
+- `onGiveawayCompleted` — a giveaway was completed;
+- `onGiveawayWinners` — the giveaway winners were published;
+- `onGiveawayContent` — a message contains giveaway content.
+
+The bot sends no replies and defines no bot commands.
+
+## Setup and permissions
+
+1. Obtain a bot token and keep it private.
+2. Add the bot to every chat whose giveaway updates it should observe, with enough
+   access for Telegram to deliver those updates.
+
+The example does not call admin-only methods, store data, or configure a webhook.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :GiveawaysBot:run --args="BOT_TOKEN"
+```
+
+The first argument is always the required bot token. Optional, case-sensitive flags
+may follow it in either order:
+
+- `debug` enables TelegramBotAPI diagnostic logging on standard output;
+- `testServer` connects to Telegram's Bot API test environment.
+
+For example:
+
+```bash
+./gradlew :GiveawaysBot:run --args="BOT_TOKEN debug testServer"
 ```

GiveawaysBot/src/main/kotlin/GiveawaysBot.kt

@@ -13,7 +13,12 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * This place can be the playground for your code.
+ * Starts a long-polling bot that prints its profile and giveaway-related updates.
+ *
+ * The first argument must be the bot token. The optional, case-sensitive `debug`
+ * and `testServer` flags enable diagnostic logging and the Bot API test environment.
+ *
+ * @param args bot token followed by any optional flags
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

GuestQueryBot/README.md

@@ -0,0 +1,50 @@
+# GuestQueryBot
+
+Demonstrates guest queries through long polling in chats where the bot is not a member.
+
+## Behavior
+
+At startup, the bot calls `getMe` and prints its bot information and the value of
+`supportsGuestQueries`.
+
+For each guest request, it prints the query ID, caller, chat, and content, then
+answers with an inline article whose message contains:
+
+```text
+Guest mode reply
+Query ID: <guest-query-id>
+```
+
+For ordinary content messages carrying guest-call metadata, the bot also replies
+with the initiating user's name and/or the public chat's title. Every received
+update is printed to standard output. The bot defines no commands.
+
+## Setup and permissions
+
+1. Create a bot and obtain its token; keep the token private.
+2. Enable guest queries in BotFather so that `supports_guest_queries` is enabled.
+3. For ordinary messages outside guest mode, add the bot to the relevant chat and
+   allow it to send messages there.
+
+The guest-query flow does not require the bot to be a chat member. This example
+uses no admin-only methods and does not configure a webhook.
+
+## Run
+
+From the repository root:
+
+```bash
+./gradlew :GuestQueryBot:run --args="BOT_TOKEN"
+```
+
+The first argument is the required bot token. Optional, case-sensitive flags may
+follow it in either order:
+
+- `debug` enables formatted library logging on standard output;
+- `testServer` connects to Telegram's Bot API test environment.
+
+For example:
+
+```bash
+./gradlew :GuestQueryBot:run --args="BOT_TOKEN debug testServer"
+```

GuestQueryBot/src/main/kotlin/GuestQueryBot.kt

@@ -19,19 +19,12 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * This bot demonstrates guest mode support introduced in Telegram Bot API.
+ * Starts the long-polling guest-query example.
  *
- * Guest mode allows bots to receive messages and reply within chats they are not a member of.
- * To enable guest queries for your bot, set `supports_guest_queries` in BotFather settings.
- *
- * Key concepts demonstrated:
- * - `supportsGuestQueries` field on the bot itself (via getMe())
- * - `GuestMessageUpdate` — a new update type for messages sent in guest mode
- * - `guestQueryId` — unique ID used to answer the guest query
- * - `guestBotCallerUser` — the user who initiated the guest query
- * - `guestBotCallerChat` — the chat from which the guest query was sent
- * - `answerGuestQuery` / `reply(GuestMessage, InlineQueryResult)` — how to respond
- * - `SentGuestMessage` — the result returned after answering, containing the inline_message_id
+ * The first element of [args] must be the bot token. The optional, case-sensitive
+ * values `debug` and `testServer` enable diagnostic logging and Telegram's test
+ * environment, respectively. Guest requests receive an inline article response;
+ * regular content messages with guest-caller metadata receive an acknowledgement.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

HelloBot/README.md

@@ -1,9 +1,43 @@
 # HelloBot
 
-The main purpose of this bot is just to answer "Oh, hi, " and add user mention here
+HelloBot is a small long-polling example that greets the chat or sender when a
+message addresses the bot by username.
 
-## Launch
+## Trigger and replies
+
+There are no slash commands. The bot handles a content message only when its
+text contains the bot's full username. This is a case-sensitive substring
+check; messages without text or without the username are ignored.
+
+- In a private chat, it replies with a MarkdownV2 text mention of the user.
+- In a group or supergroup, it greets the group and links its title to a public
+  username or invite link when one is available.
+- For a message sent to a group on behalf of a channel, it greets the sender
+  channel instead.
+- In a channel, it greets the channel and includes the sender chat when Telegram
+  supplies one.
+- In a business chat, it mentions the underlying private-chat user.
+
+Every received update is also printed to standard output for demonstration and
+debugging.
+
+## Setup
+
+1. Create a bot with BotFather and keep its token private.
+2. Add the bot to each chat where it should respond. Explicit username mentions
+   work with Telegram's normal group privacy mode.
+3. For channel posts, make the bot a channel administrator and allow it to post
+   messages. Admin access may also make a private group invite link available;
+   otherwise the group reply falls back to an unlinked title.
+
+## Run
+
+From the repository root, pass the token as the first positional argument:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :HelloBot:run --args="BOT_TOKEN"
 ```
+
+The token is required. Additional command-line arguments are ignored. The bot
+runs until the process is stopped and uses long polling, so no webhook setup is
+needed.

HelloBot/src/main/kotlin/HelloBot.kt

@@ -18,7 +18,13 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * The main purpose of this bot is just to answer "Oh, hi, " and add user mention here
+ * Starts HelloBot with long polling and logs every received update.
+ *
+ * Content messages are handled when their text contains the bot's full
+ * username. The reply varies for private, group, channel, and business chats.
+ *
+ * @param args the bot token at index `0`; any remaining arguments are ignored
+ * @throws NoSuchElementException when no bot token is supplied
  */
 @OptIn(PreviewFeature::class)
 suspend fun main(vararg args: String) {

InlineQueriesBot/README.md

@@ -1,9 +1,51 @@
 # InlineQueriesBot
 
-This bot will form the inline queries for you. For that feature you should explicitly enable inline queries in bot settings
+This Kotlin Multiplatform example answers inline queries with generated article results. It uses long polling and can be
+launched on the JVM or as a Kotlin/Native executable.
 
-## Launch
+## Behavior
+
+For every inline query, the bot:
+
+- treats the numeric `offset` as a page number, defaulting to page `0` when the offset is absent or invalid;
+- returns a full page of numbered articles whose message text includes the user's query;
+- disables caching and marks the answer as personal;
+- provides the next numeric offset for pagination; and
+- adds a button that opens a `/start` deep link for the current page. The bot replies with that deep-link parameter.
+
+The bot also prints its own account information at startup, logs received updates, and prints polling exceptions.
+
+## Setup
+
+Create a bot and obtain its token, then enable inline mode for it in BotFather (for example, with `/setinline`). Keep the
+token private.
+
+Both launchers require the bot token as the first command-line argument. Starting either launcher without an argument
+fails immediately; additional arguments are ignored.
+
+## Launch from the repository root
+
+### JVM
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :InlineQueriesBot:runJvm --args="<BOT_TOKEN>"
 ```
+
+### Kotlin/Native
+
+The shared native configuration supports Linux x64/Arm64 and Windows x64 hosts. Build the debug executable with Gradle,
+then pass the token directly to the produced program:
+
+```bash
+./gradlew :InlineQueriesBot:linkDebugExecutableNative
+./InlineQueriesBot/build/bin/native/debugExecutable/InlineQueriesBot.kexe "<BOT_TOKEN>"
+```
+
+On Windows, run `InlineQueriesBot\build\bin\native\debugExecutable\InlineQueriesBot.exe "<BOT_TOKEN>"` after the same
+Gradle link task.
+
+## Source sets
+
+- `commonMain` contains `doInlineQueriesBot`, including the long-polling behavior and inline-query/deep-link handlers.
+- `jvmMain` provides the suspending JVM entry point.
+- `nativeMain` provides the native entry point and calls the shared suspending function with `runBlocking`.

InlineQueriesBot/src/commonMain/kotlin/Bot.kt

@@ -14,8 +14,7 @@ import dev.inmo.tgbotapi.types.inlineQueryAnswerResultsLimit
 import dev.inmo.tgbotapi.utils.buildEntities
 
 /**
- * Thi bot will create inline query answers. You
- * should enable inline queries in bot settings
+ * Starts the inline-query bot with [token] and suspends until long polling stops.
  */
 suspend fun doInlineQueriesBot(token: String) {
     val bot = telegramBot(token)

InlineQueriesBot/src/jvmMain/kotlin/InlineQueriesBot.kt

@@ -1,3 +1,4 @@
+/** JVM entry point; [args] must contain the bot token as its first element. */
 suspend fun main(args: Array<String>) {
     doInlineQueriesBot(args.first())
 }

InlineQueriesBot/src/nativeMain/kotlin/InlineQueriesBot.kt

@@ -1,5 +1,6 @@
 import kotlinx.coroutines.runBlocking
 
+/** Kotlin/Native entry point; [args] must contain the bot token as its first element. */
 fun main(args: Array<String>) {
     runBlocking {
         doInlineQueriesBot(args.first())

JoinRequestQueriesBot/README.md

@@ -0,0 +1,48 @@
+# JoinRequestQueriesBot
+
+A long-polling example for processing chat join-request queries as a chat's guard bot.
+
+## Behavior
+
+At startup, the bot calls `getMe` and prints its bot information and
+`supportsJoinRequestQueries` value. For every chat join request it prints the
+requesting user, chat, bio, query ID, and the chat's configured guard bot.
+
+Only requests containing a query ID are processed. Without a Web App URL, the bot:
+
+- answers with `Queue` when the user's bio is missing or blank, leaving the
+  decision to other administrators;
+- answers with `Approve` when the user has a nonblank bio.
+
+When an HTTPS Web App URL is supplied, the bot sends that Web App for verification
+instead of answering the query. Requests without a query ID are only logged. Every
+received update is printed to standard output, and the bot defines no commands.
+
+## Setup and permissions
+
+1. Create a bot, obtain its token, and keep the token private.
+2. Configure the bot as the guard bot of the chat whose requests it should handle.
+3. Grant it the administrator permission to invite users (`can_invite_users`).
+4. If using the Web App flow, provide an HTTPS verification URL.
+
+The example uses long polling and does not configure a webhook. Be aware that its
+default flow automatically approves query-backed requests with a nonblank bio.
+
+## Run
+
+From the repository root:
+
+```bash
+./gradlew :JoinRequestQueriesBot:run --args="BOT_TOKEN"
+```
+
+The first argument is the required bot token. An optional Web App URL is recognized
+only as the second argument and must begin with `https://`. The case-sensitive flags
+`debug` and `testServer` enable formatted logging and Telegram's test environment;
+they may follow the token and Web App URL.
+
+For example:
+
+```bash
+./gradlew :JoinRequestQueriesBot:run --args="BOT_TOKEN https://example.com/verify debug"
+```

JoinRequestQueriesBot/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'kotlin'
+apply plugin: 'application'
+
+mainClassName="JoinRequestQueriesBotKt"
+
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    implementation "dev.inmo:tgbotapi:$telegram_bot_api_version"
+}

JoinRequestQueriesBot/src/main/kotlin/JoinRequestQueriesBot.kt

@@ -0,0 +1,95 @@
+import dev.inmo.kslog.common.KSLog
+import dev.inmo.kslog.common.LogLevel
+import dev.inmo.kslog.common.defaultMessageFormatter
+import dev.inmo.kslog.common.setDefaultKSLog
+import dev.inmo.micro_utils.coroutines.subscribeLoggingDropExceptions
+import dev.inmo.tgbotapi.extensions.api.bot.getMe
+import dev.inmo.tgbotapi.extensions.api.chat.get.getChat
+import dev.inmo.tgbotapi.extensions.api.chat.invite_links.answerChatJoinRequestQuery
+import dev.inmo.tgbotapi.extensions.api.chat.invite_links.sendChatJoinRequestWebApp
+import dev.inmo.tgbotapi.extensions.behaviour_builder.telegramBotWithBehaviourAndLongPolling
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onChatJoinRequest
+import dev.inmo.tgbotapi.requests.chat.invite_links.ChatJoinRequestQueryResult
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+
+/**
+ * Starts the long-polling join-request-query example.
+ *
+ * The first element of [args] must be the bot token. When the second element is an
+ * `https://` URL, query-backed requests are handed to that Web App. Otherwise, the
+ * bot queues requests with a blank bio and approves those with a nonblank bio.
+ * The optional exact values `debug` and `testServer` enable diagnostic logging and
+ * Telegram's test environment, respectively.
+ */
+suspend fun main(vararg args: String) {
+    val botToken = args.first()
+    val isDebug = args.any { it == "debug" }
+    val isTestServer = args.any { it == "testServer" }
+    // pass a https url as the second argument to demonstrate sendChatJoinRequestWebApp
+    val webAppUrl = args.getOrNull(1) ?.takeIf { it.startsWith("https://") }
+
+    if (isDebug) {
+        setDefaultKSLog(
+            KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
+                println(defaultMessageFormatter(level, tag, message, throwable))
+            }
+        )
+    }
+
+    telegramBotWithBehaviourAndLongPolling(
+        botToken,
+        CoroutineScope(Dispatchers.IO),
+        testServer = isTestServer
+    ) {
+        val me = getMe()
+        println("Bot info: $me")
+        // supportsJoinRequestQueries reflects the supports_join_request_queries field from the Telegram API
+        println("Supports join request queries: ${me.supportsJoinRequestQueries}")
+
+        onChatJoinRequest { request ->
+            println("=== Chat join request received ===")
+            println("  from:        ${request.from}")
+            println("  chat:        ${request.chat}")
+            println("  bio:         ${request.bio}")
+            // queryId is non-null only when the request arrives as a query to this bot as the guard bot
+            println("  queryId:     ${request.queryId}")
+
+            // guardBot is the bot processing join request queries in this chat (admins-only field)
+            val guardBot = runCatching { getChat(request.chat).guardBot }.getOrNull()
+            println("  guardBot:    $guardBot")
+
+            val queryId = request.queryId
+            if (queryId == null) {
+                println("  -> request has no queryId, this bot is not the guard bot here")
+                return@onChatJoinRequest
+            }
+
+            if (webAppUrl != null) {
+                // sendChatJoinRequestWebApp: hand the user a Web App (e.g. captcha) instead of deciding now
+                sendChatJoinRequestWebApp(request, webAppUrl)
+                println("  -> sent join request Web App: $webAppUrl")
+                return@onChatJoinRequest
+            }
+
+            // answerChatJoinRequestQuery with one of the ChatJoinRequestQueryResult variants:
+            //   Approve  — allow the user to join
+            //   Decline  — disallow the user to join
+            //   Queue    — leave the decision to other administrators
+            //   Unknown  — any future result not yet known to the library
+            val result = if (request.bio.isNullOrBlank()) {
+                // no bio -> let other admins decide
+                ChatJoinRequestQueryResult.Queue
+            } else {
+                // has a bio -> approve
+                ChatJoinRequestQueryResult.Approve
+            }
+            answerChatJoinRequestQuery(request, result)
+            println("  -> answered with: ${result.name}")
+        }
+
+        allUpdatesFlow.subscribeLoggingDropExceptions(scope = this) {
+            println(it)
+        }
+    }.second.join()
+}

KeyboardsBot/KeyboardsBotLib/src/commonMain/kotlin/KeyboardsBot.kt

@@ -25,6 +25,11 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.currentCoroutineContext
 
+/**
+ * Parses pagination callback data whose first two space-separated fields are the page and total page count.
+ *
+ * @return the parsed page and count, or `null` when either field is missing or is not an integer
+ */
 fun String.parsePageAndCount(): Pair<Int, Int>? {
     val (pageString, countString) = split(" ").takeIf { it.count() > 1 } ?: return null
     return Pair(
@@ -33,6 +38,15 @@ fun String.parsePageAndCount(): Pair<Int, Int>? {
     )
 }
 
+/**
+ * Adds the pagination controls used by command replies and inline-query results.
+ *
+ * The controls include nearby page callbacks, first/last-page jumps when applicable, a button that copies the
+ * corresponding `/inline` command, and a button that starts inline mode for a user-selected chat.
+ *
+ * @param page the current page; callers should keep it within `1..count`
+ * @param count the total number of pages; callers should pass a positive value
+ */
 fun InlineKeyboardBuilder.includePageButtons(page: Int, count: Int) {
     val numericButtons = listOfNotNull(
         page - 1,
@@ -78,6 +92,15 @@ fun InlineKeyboardBuilder.includePageButtons(page: Int, count: Int) {
     }
 }
 
+/**
+ * Creates and runs the shared KeyboardsBot behavior using long polling.
+ *
+ * The bot serves `/inline` pagination keyboards, edits them in response to callback queries, answers compatible
+ * inline queries, offers an `/inline` reply-keyboard button for unhandled commands, and logs every received update.
+ *
+ * @param token the Telegram bot token
+ * @param print receives the bot information returned by the startup `getMe` request
+ */
 @OptIn(PreviewFeature::class)
 suspend fun activateKeyboardsBot(
     token: String,

KeyboardsBot/KeyboardsBotLib/src/jsMain/kotlin/KeyboardsBot.kt

@@ -4,6 +4,12 @@ import org.w3c.dom.*
 
 private val scope = CoroutineScope(Dispatchers.Default)
 
+/**
+ * Installs the browser launch form after `DOMContentLoaded`.
+ *
+ * Every submission reads the token from `bot_token`, appends a result container under `bots_container`, and launches
+ * [activateKeyboardsBot]. The result of its startup `getMe` request is rendered in that new container.
+ */
 fun main() {
     document.addEventListener(
         "DOMContentLoaded",

KeyboardsBot/README.md

@@ -0,0 +1,66 @@
+# KeyboardsBot
+
+A multiplatform long-polling example that demonstrates Telegram reply keyboards, inline keyboards, callback queries, copy-text buttons, inline-mode buttons, and keyboard button styles. The shared bot behavior lives in `KeyboardsBotLib`; the project provides a browser/JS entry point and a separate JVM launcher.
+
+## Bot behavior
+
+At startup, the bot calls `getMe`, reports the returned bot information through the platform launcher, registers `/inline` with Telegram, and starts long polling. Every received update is also printed to the JVM terminal or browser developer console.
+
+### Commands
+
+| Command | Result |
+| --- | --- |
+| `/inline` | Opens page `1` of a `10`-page inline keyboard. |
+| `/inline <count>` | Opens page `1` with the supplied total page count. |
+| `/inline <page> <count>` | Opens the supplied page with the supplied total page count. |
+
+Only numeric command arguments are considered. Use positive integers with `page <= count`; the example does not validate the count or clamp the page to the upper bound.
+
+The generated inline keyboard contains:
+
+- numbered buttons for the current page and any adjacent pages that are within `1..count`;
+- styled jump buttons for moving toward the first or last page when applicable;
+- a **Command copy button** that copies `/inline <page> <count>`;
+- a **Send somebody page** button that starts inline mode and lets the user choose a user, bot, group, or channel.
+
+Pagination callbacks edit the original message and replace its text with `This is <page> of <count>`. This works for both ordinary bot messages and messages sent through inline mode. Unsupported callback data or an unsupported message type is answered with a callback notification instead.
+
+Any command not handled above, including `/start`, receives a one-time reply keyboard containing a styled `/inline` button. Ordinary non-command messages are ignored.
+
+### Inline mode
+
+With inline mode enabled, a query beginning with a page and count, such as `@YourBot 2 10`, returns one **Send buttons** article. Sending that result posts an inline-mode message with the same pagination keyboard.
+
+## Telegram setup
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Enable inline mode for the bot with BotFather's `/setinline` command. Direct `/inline` commands work without it, but inline queries and **Send somebody page** require it.
+3. Run only one launcher for a token at a time. The bot receives updates through long polling and automatically removes an existing webhook when it starts.
+
+The browser launcher handles the token in client-side code. Use it only from a trusted local page, do not expose the page publicly with a token filled in, and close the page when the bot should stop.
+
+## Launch
+
+Run the commands below from the repository root.
+
+### JVM
+
+The first argument is the required bot token. An optional argument exactly equal to `debug` enables formatted KSLog output; the token must remain first.
+
+```bash
+./gradlew :KeyboardsBot:jvm_launcher:run --args="<BOT_TOKEN>"
+```
+
+```bash
+./gradlew :KeyboardsBot:jvm_launcher:run --args="<BOT_TOKEN> debug"
+```
+
+### Browser/JS
+
+Start the Kotlin/JS browser development run:
+
+```bash
+./gradlew :KeyboardsBot:KeyboardsBotLib:jsBrowserDevelopmentRun
+```
+
+Enter the bot token in the displayed form and press **Start bot**. The page displays the result of `getMe`; raw updates and other console output appear in the browser developer console. Each form submission starts another bot instance, so submit the token only once.

KeyboardsBot/jvm_launcher/src/main/kotlin/KeyboardsBotJvm.kt

@@ -5,6 +5,12 @@ import dev.inmo.kslog.common.setDefaultKSLog
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 
+/**
+ * Runs [activateKeyboardsBot] on the JVM and prints its startup bot information to standard output.
+ *
+ * @param args the bot token as the first element and, optionally, `debug` in a later element to enable formatted
+ * KSLog output
+ */
 suspend fun main(args: Array<String>) {
     val isDebug = args.any { it == "debug" }
 

LinkPreviewsBot/README.md

@@ -1,9 +1,47 @@
-# ReactionsInfoBot
+# LinkPreviewsBot
 
-This bot will resend messages with links with all variants of `LinkPreviewOptions`
+A long-polling example that resends text-bearing content with every demonstrated
+`LinkPreviewOptions` variant.
 
-## Launch
+## Behavior
+
+The bot handles every content message. It searches the message's text entities for
+the first plain URL or text-link entity. When one is found, it sends the same text
+and entities to the same chat seven times:
+
+- with link previews disabled;
+- with a large preview above the text;
+- with a large preview below the text;
+- with a small preview above the text;
+- with a small preview below the text;
+- with Telegram's default preview size above the text;
+- with Telegram's default preview size below the text.
+
+The detected URL is selected explicitly for each enabled preview. If the content is
+not text-bearing or contains no URL entity, the bot replies that only content with
+a URL is supported. It defines and registers no commands.
+
+## Setup and permissions
+
+1. Create a bot, obtain its token, and keep the token private.
+2. Start a private chat with it, or add it to a chat where previews should be tested.
+3. Ensure Telegram delivers the relevant content messages and the bot may send
+   messages in that chat.
+
+The example uses no administrator-only methods and does not configure a webhook.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :LinkPreviewsBot:run --args="BOT_TOKEN"
+```
+
+The first argument is the required bot token. The optional, case-sensitive second
+argument `debug` enables formatted library logging on standard output. Arguments
+after the second are ignored.
+
+```bash
+./gradlew :LinkPreviewsBot:run --args="BOT_TOKEN debug"
 ```

LinkPreviewsBot/src/main/kotlin/LinkPreviewsBot.kt

@@ -15,7 +15,12 @@ import dev.inmo.tgbotapi.types.message.content.TextedContent
 import dev.inmo.tgbotapi.utils.regular
 
 /**
- * This bot will reply with the same
+ * Starts a long-polling bot that demonstrates link-preview layouts.
+ *
+ * The first element of [args] must be the bot token. An optional exact `debug`
+ * value in the second position enables diagnostic logging. For each text-bearing
+ * content message, the bot uses its first URL entity to send one disabled-preview
+ * copy and large, small, and default previews both above and below the text.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

LiveLocationsBot/README.md

@@ -1,9 +1,39 @@
 # LiveLocationsBot
 
-This bot will send you live location and update it from time to time
+A long-polling example that sends, updates, and stops a live-location message.
 
-## Launch
+## Commands and behavior
+
+- `/start` begins a live-location sequence in the command's chat.
+- `Cancel`, an inline button on the live-location message, stops that sequence.
+
+The generated coordinates are synthetic: the first update uses latitude and
+longitude `(0.0, 0.0)`, and both values increase by `1.0` for each later update.
+The bot emits an update immediately and then every three seconds.
+
+While the sequence runs, the bot tracks its current location message. It accepts
+only callback data equal to `cancel` from that same message. After a matching button
+press, it cancels the update job, stops the live location, and removes the button.
+
+Every received update is printed to standard output. The `/start` handler is not
+separately registered in Telegram's command menu.
+
+## Setup and permissions
+
+1. Create a bot, obtain its token, and keep the token private.
+2. Start a private chat with the bot, or add it to a group where the demo should run.
+3. Allow the bot to send location messages in that chat.
+
+The coordinates do not come from the user's device. The example needs no
+administrator-only methods and does not configure a webhook.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :LiveLocationsBot:run --args="BOT_TOKEN"
 ```
+
+The first argument is the required bot token. Omitting it causes startup to fail;
+additional arguments are ignored. Stop the process with `Ctrl+C`.

LiveLocationsBot/src/main/kotlin/LiveLocationsBot.kt

@@ -18,7 +18,12 @@ import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.flow
 
 /**
- * This bot will send you live location and update it from time to time
+ * Starts the long-polling live-location example.
+ *
+ * The first element of [args] must be the bot token; later elements are ignored.
+ * Each `/start` command begins a synthetic location at `(0.0, 0.0)`, advances both
+ * coordinates every three seconds, and stops when the current message's `Cancel`
+ * button is pressed.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
@@ -64,4 +69,3 @@ suspend fun main(vararg args: String) {
         allUpdatesFlow.subscribeLoggingDropExceptions(this) { println(it) }
     }.second.join()
 }
-

LivePhotosBot/README.md

@@ -0,0 +1,54 @@
+# LivePhotosBot
+
+This long-polling example demonstrates receiving, sending, grouping, editing, and selling Telegram Live Photos. It also shows how a regular photo and video from one album can be reused as the two parts of a Live Photo.
+
+## Behavior, commands, and triggers
+
+The bot defines no commands. It prints every incoming update to standard output in addition to the trigger-specific output below.
+
+| Trigger | Behavior |
+| --- | --- |
+| Standalone Live Photo | Logs its file identifiers, dimensions, duration, thumbnail, MIME type, size, and caption. It resends the Live Photo, sends the same media as paid content costing 1 Star, and then edits the resent message with `TelegramMediaLivePhoto`. |
+| Live Photo gallery | Logs every item and resends the gallery with `sendMediaGroup`. |
+| Paid-media message containing Live Photos | Logs each Live Photo and replies with the number found. Paid-media messages without a Live Photo get no reply from this handler. |
+| Edited Live Photo | Logs the file ID and updated caption. |
+| Media group containing at least one regular photo and one regular video | Uses the first photo as the cover and the first video as the motion part, then replies with a Live Photo. Albums missing either type are ignored by this handler. |
+
+## Live Photo handling
+
+The bot does not download or transform media. It reuses Telegram file IDs: the received Live Photo is passed directly to `sendLivePhoto`, while its main file ID and thumbnail file ID are used to construct `TelegramMediaLivePhoto` and `TelegramPaidMediaLivePhoto`. If Telegram supplies no thumbnail, the code falls back to the main file ID for the photo field.
+
+The standalone handler performs its requests in order: resend, send paid media, then edit the resent message. Consequently, a failure while sending paid media prevents the edit for that update.
+
+## Telegram setup and permissions
+
+1. Create a bot with BotFather and obtain its token.
+2. Add the bot to the chat where you want to exercise the example and allow it to send messages and media.
+3. In a group, make the bot an administrator or disable Group Privacy Mode so it receives ordinary, non-command media albums and Live Photos.
+4. To complete the standalone Live Photo flow, use a channel and grant the bot permission to post there: Telegram restricts `sendPaidMedia` to channel chats. In other chat types, the initial resend may succeed but the paid-media request can fail before the edit runs.
+
+The program does not request or validate permissions itself. API errors use the library's normal handling.
+
+## Arguments
+
+The first argument is the required bot token. Optional flags are exact and case-sensitive, can follow the token in either order, and unknown extra arguments are ignored.
+
+| Argument | Effect |
+| --- | --- |
+| `<BOT_TOKEN>` | Bot token. Omitting it fails before polling starts. |
+| `debug` | Prints formatted KSLog diagnostics to standard output. |
+| `testServer` | Uses Telegram's Bot API test environment. |
+
+## Launch
+
+From the repository root:
+
+```bash
+./gradlew :LivePhotosBot:run --args="<BOT_TOKEN>"
+```
+
+For example, to enable both optional flags:
+
+```bash
+./gradlew :LivePhotosBot:run --args="<BOT_TOKEN> debug testServer"
+```

LivePhotosBot/src/main/kotlin/LivePhotosBot.kt

@@ -37,16 +37,10 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * This bot demonstrates Live Photos support introduced in Telegram Bot API.
+ * Starts the long-polling example for receiving, sending, grouping, editing, and selling Live Photos.
  *
- * Key concepts demonstrated:
- * - [dev.inmo.tgbotapi.types.files.LivePhotoFile] — the LivePhoto class: a photo with an attached short video
- * - [TelegramMediaLivePhoto] — InputMediaLivePhoto: used in sendMediaGroup and editMessageMedia
- * - [LivePhotoContent] — the content type carried in Message.live_photo / ExternalReplyInfo.live_photo
- * - [sendLivePhoto] — method to send a live photo
- * - [PaidMedia.LivePhoto] — PaidMediaLivePhoto: a live photo inside paid media content
- * - [TelegramPaidMediaLivePhoto] — InputPaidMediaLivePhoto: used in sendPaidMedia
- * - sendMediaGroup and editMessageMedia with live photos
+ * @param args bot token followed by the optional, case-sensitive `debug` and `testServer` flags; unknown trailing
+ * arguments are ignored
  */
 @OptIn(RiskFeature::class)
 suspend fun main(vararg args: String) {

ManagedBotsBot/README.md

@@ -0,0 +1,53 @@
+# ManagedBotsBot
+
+A long-polling playground for creating and administering managed bots, inspecting a
+user's personal-channel messages, and trying bot-to-bot messages.
+
+## Commands and triggers
+
+- `/start` prints the triggering update, context data, and full chat information;
+  it sends no reply.
+- `/canManageBots` replies whether `getMe` reports that this bot can manage bots.
+- `/keyboard` sends a one-time keyboard for creating a managed bot with suggested
+  name `SampleName` and username `@some_sample_bot`.
+- `/replaceToken`, when sent as a reply to a managed-bot-created service message,
+  replaces that bot's token and replies with the new token.
+- `/get_bot_access_settings <botId>` shows whether access is restricted and lists
+  allowed users when present.
+- `/set_bot_access_settings <botId> [userId ...]` restricts access to the supplied
+  numeric user IDs; omitting user IDs opens access to everyone.
+- `/get_personal_messages` lists up to ten messages from the current private-chat
+  user's linked personal channel.
+- `/send_to_bot @username [text]` sends text to another bot; omitted text defaults
+  to `Hello from bot-to-bot communication!`.
+
+Managed-bot-created and managed-bot-updated events report the bot and numeric ID,
+then retrieve and send its token and access settings. Every update and every API
+request result is also printed to standard output. Commands are not registered in
+Telegram's command menu.
+
+## Setup, permissions, and safety
+
+1. Create a bot, obtain its token, and verify `/canManageBots` replies `Yes`.
+2. Use a private test chat for the managed-bot and personal-channel examples.
+3. Link a personal channel before using `/get_personal_messages`.
+4. For `/send_to_bot`, enable bot-to-bot communication for both bots in BotFather.
+
+This example exposes managed-bot tokens in chat and logs API results. Use disposable
+test bots, keep the chat and process output private, and rotate any exposed token.
+No chat-administrator permission is requested by the code.
+
+## Run
+
+The intended command from the repository root is:
+
+```bash
+./gradlew :ManagedBotsBot:run --args="BOT_TOKEN"
+```
+
+The first argument is the required token. Optional exact flags may follow it in any
+order: `debug` enables formatted logging, and `testServer` uses Telegram's test API.
+
+Known issue: `build.gradle` currently sets `mainClassName` to `CustomBotKt`, while
+this source's entry point is `ManagedBotsBotKt`; the `run` task cannot start until
+that Gradle setting is corrected.

ManagedBotsBot/src/main/kotlin/ManagedBotsBot.kt

@@ -48,7 +48,12 @@ private var BehaviourContextData.commonMessage: ChatContentMessage<*>?
     set(value) = set("commonMessage", value)
 
 /**
- * This place can be the playground for your code.
+ * Starts the long-polling managed-bot playground.
+ *
+ * The first element of [args] must be the bot token. Optional exact values `debug`
+ * and `testServer` enable diagnostic logging and Telegram's test environment.
+ * The handlers expose managed-bot creation, tokens, access settings, personal-chat
+ * messages, and bot-to-bot messaging; API results and all updates are logged.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

MemberUpdatedWatcherBot/README.md

@@ -1,10 +1,49 @@
 # MemberUpdatedWatcherBot
 
-This bot will watch for some ChatMemberUpdated events using new extensions from 18.0.0
+A long-polling example that watches Telegram `my_chat_member` and `chat_member` updates, logs membership transitions, and posts human-readable notifications in the affected chat. It has no commands and does not respond to ordinary messages.
 
+## Behavior
+
+The bot handles these transitions:
+
+- **Joined:** logs the old and new member-state types and sends `Welcome <first name>`.
+- **Left or removed:** logs the transition and sends `Goodbye <first name>`.
+- **Promoted:** logs the new administrator title and announces it. A promotion also matches the administrator-permissions-change handler, so it produces a second permissions-change notification.
+- **Demoted:** logs the transition and announces that the user was demoted back to member.
+- **Administrator permissions/title changed:** logs and sends the old and new member-state types.
+- **Newly restricted or restrictions changed:** logs and sends the old and new member-state types. Removing all restrictions is not handled separately.
+
+The bot also identifies updates about itself:
+
+- when added, it asks the chat to grant it administrator permissions;
+- when promoted, it confirms that it can now watch other users;
+- when demoted, it warns that it can no longer watch other users.
+
+The general handlers do not exclude the bot's own updates. Adding, promoting, or demoting the bot can therefore also produce the corresponding generic welcome, promotion, permissions-change, or demotion messages.
+
+Event details are always written to standard output with the `ChatMemberUpdates` log tag. Debug mode additionally routes the library's default KSLog output to standard output.
+
+## Telegram setup, permissions, and privacy
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Add it to the group or supergroup that should be watched.
+3. Promote it to administrator. Telegram exposes updates about the bot's own membership without this step, but delivers `chat_member` updates about other users only to administrators. The long-polling setup requests that update type.
+4. Ensure the bot can send messages in the chat. If using the example in a channel, it also needs permission to post messages.
+
+BotFather privacy mode may remain enabled: privacy mode controls which messages a bot receives in groups, not member-status updates. The bot does not need access to ordinary group messages.
+
+The example uses long polling and automatically removes an existing webhook at startup. Run only one update consumer for the bot token at a time.
 
 ## Launch
 
+From the repository root, pass the bot token as the first application argument:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :MemberUpdatedWatcherBot:run --args="<BOT_TOKEN>"
+```
+
+Add an argument exactly equal to `debug` after the token to enable formatted library logging. Other additional arguments are ignored.
+
+```bash
+./gradlew :MemberUpdatedWatcherBot:run --args="<BOT_TOKEN> debug"
 ```

MemberUpdatedWatcherBot/src/main/kotlin/MemberUpdatedWatcher.kt

@@ -12,6 +12,15 @@ import dev.inmo.tgbotapi.types.chat.member.*
 import dev.inmo.tgbotapi.utils.*
 
 
+/**
+ * Runs a long-polling bot that logs selected chat-member transitions and announces them in the affected chat.
+ *
+ * Updates about the bot itself produce setup/status messages, while joins, departures, promotions, demotions,
+ * administrator changes, and restriction changes produce member notifications.
+ *
+ * @param args the bot token as the first element and, optionally, `debug` in a later element to enable formatted
+ * default KSLog output
+ */
 @OptIn(PreviewFeature::class)
 suspend fun main(args: Array<String>) {
     val token = args.first()
@@ -95,4 +104,4 @@ suspend fun main(args: Array<String>) {
             send(it.chat.id, message)
         }
     }.join()
-}
+}

MyBot/README.md

@@ -1,9 +1,45 @@
-# GetMeBot
+# MyBot
 
-This is one of the most easiest bot - it will just print information about itself
+A long-polling example that prints information about the bot and lets Telegram users replace or remove its global profile photo.
+
+## Behavior
+
+At startup, the application prints the results of `getMe` and `getChat` for the bot itself to standard output. It then handles two commands:
+
+- `/setMyProfilePhoto` replies with `ok, send me new photo` and waits for the first photo sent in the same chat. It streams draft progress messages while downloading the photo to a temporary file, uploads it as a static bot profile photo, and replies when the change is complete. The photo may come from any user in that chat; it is not restricted to the user who sent the command.
+- `/removeMyProfilePhoto` removes the bot's current profile photo and confirms success. On failure, it prints the exception and sends a generic error reply.
+
+There is no `/start` handler, and ordinary messages are ignored unless the bot is waiting for a photo after `/setMyProfilePhoto`.
+
+## Setup and permissions
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- No chat-administrator permission is required to change the bot's own profile photo. In a group, the bot still needs permission to send replies.
+- Prefer using this example in a private chat. Telegram's draft-message API is intended for private chats, and BotFather privacy mode can prevent an unrelated group photo from reaching the bot unless it is sent as a reply or privacy mode is disabled.
+- This example performs no authorization checks: anyone who can reach the commands can change or remove the bot's profile photo globally. Do not expose a production bot without adding access control.
+- Long polling automatically removes an existing webhook at startup. Run only one update consumer for the token at a time.
+
+## Arguments
+
+The first argument is always the required bot token. Optional arguments can follow it in any order:
+
+- `debug` enables formatted default KSLog output.
+- `testServer` makes the behavior and long-polling client use Telegram's Bot API test environment. The initial `getMe` and `getChat` diagnostics currently use a separate default-server client.
+
+Other arguments are ignored. Argument matching is case-sensitive.
 
 ## Launch
 
+The intended command from the repository root is:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :MyBot:run --args="<BOT_TOKEN>"
 ```
+
+For example, to enable both optional modes:
+
+```bash
+./gradlew :MyBot:run --args="<BOT_TOKEN> debug testServer"
+```
+
+> **Known issue:** `MyBot/build.gradle` still declares the old `GetMeBotKt` main class, while the current source produces `MyBotKt`. Consequently, the `run` task cannot start until that build setting is corrected. It is left unchanged here because this example update is documentation-only.

MyBot/src/main/kotlin/MyBot.kt

@@ -26,7 +26,13 @@ import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 
 /**
- * This is one of the easiest bots - it will just print information about itself
+ * Runs the MyBot profile-photo example using long polling.
+ *
+ * Startup bot information is printed to standard output. The bot then handles commands that replace its profile
+ * photo from the next photo received in the same chat or remove its current profile photo.
+ *
+ * @param args the bot token first, followed optionally by `debug` for formatted KSLog output and/or `testServer` for
+ * the Telegram Bot API test environment
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

PollsBot/README.md

@@ -1,11 +1,57 @@
 # PollsBot
 
-This bot will send test poll in the chat where commands will be received. Commands:
+A long-polling showcase for regular polls, quizzes, poll media, targeting, and
+poll-related updates. It registers all nine commands in Telegram's command menu.
 
+## Commands
 
+| Command | Behavior |
+| --- | --- |
+| `/anonymous` | Sends an anonymous poll with ten numbered options. |
+| `/public` | Sends a nonanonymous ten-option poll, allows added options, and hides results until closure. |
+| `/quiz` | Sends a nonanonymous, shuffled quiz with revoting and hidden results; it randomly collects zero to seven distinct correct options and allows multiple answers when needed. |
+| `/media_poll` | Adds location media to the question and venue/location media to options; replying to a sticker adds it as another option. |
+| `/quiz_media` | Asks where the Eiffel Tower is, with location question media, Paris as the answer, and venue explanation media. |
+| `/members_only` | Sends an anonymous Yes/No poll restricted to members. |
+| `/country_codes` | Sends an anonymous poll targeted to `US`, `DE`, and `JP`. |
+| `/single_option` | Sends a nonanonymous poll containing only `Got it`. |
+| `/link_poll` | Sends a nonanonymous poll whose first two options carry link media. |
 
-## Launch
+`/anonymous`, `/public`, and `/quiz` may contain extra text; the first custom-emoji
+entity after the command is copied into the poll's text and options.
+
+## Poll lifecycle and triggers
+
+The bot keeps an in-memory poll-ID-to-chat map for polls it sends. Poll answers
+produce a chat notification naming the answering user or voter chat. Poll updates
+report anonymity, media, member/country restrictions, quiz explanation media, and
+each option's votes and media.
+
+Added or deleted poll-option events produce replies containing the option text. A
+content message associated with a poll-option reply produces `Reply to poll option`
+on that option. Every received update is printed to standard output.
+
+There is no command to close a poll. Restarting the bot clears its routing map, so
+later answers and updates for earlier polls are no longer reported to their chats.
+
+## Setup and permissions
+
+Create a bot, keep its token private, and start it in a private chat or add it to a
+group where it may send messages and polls. No administrator-only methods or webhook
+configuration are used. Some poll targeting or media features require a Telegram
+chat and client that support them.
+
+## Run
+
+The intended command from the repository root is:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :PollsBot:run --args="BOT_TOKEN"
 ```
+
+The first argument is the required token. An optional exact `debug` argument in any
+later position enables formatted logging; other arguments are ignored.
+
+Known issue: `build.gradle` currently names `HelloBotKt` as the main class, while
+this source's entry point is `PollsBotKt`; the `run` task cannot start until that
+Gradle setting is corrected.

PollsBot/src/main/kotlin/PollsBot.kt

@@ -25,6 +25,7 @@ import dev.inmo.tgbotapi.types.BotCommand
 import dev.inmo.tgbotapi.types.IdChatIdentifier
 import dev.inmo.tgbotapi.types.PollId
 import dev.inmo.tgbotapi.types.ReplyParameters
+import dev.inmo.tgbotapi.types.media.TelegramMediaLink
 import dev.inmo.tgbotapi.types.media.TelegramMediaLocation
 import dev.inmo.tgbotapi.types.media.TelegramMediaSticker
 import dev.inmo.tgbotapi.types.media.TelegramMediaVenue
@@ -43,22 +44,13 @@ import kotlinx.coroutines.sync.withLock
 import kotlin.random.Random
 
 /**
- * This bot demonstrates poll features including the new API additions:
+ * Starts the long-polling poll-feature showcase.
  *
- * * `/anonymous` — anonymous regular poll
- * * `/public` — public regular poll with option adding
- * * `/quiz` — quiz poll with random correct answer
- * * `/media_poll` — poll with [TelegramMediaLocation] as poll media (InputMediaLocation),
- *   and [TelegramMediaVenue] as option media (InputMediaVenue / InputPollOptionMedia)
- * * `/quiz_media` — quiz poll with [TelegramMediaLocation] as `media` and [TelegramMediaVenue]
- *   as `explanationMedia` (new [QuizPoll.explanationMedia] field)
- * * `/members_only` — poll with `membersOnly = true` (new [dev.inmo.tgbotapi.types.polls.Poll.membersOnly] field)
- * * `/country_codes` — poll with `countryCodes` (new [dev.inmo.tgbotapi.types.polls.Poll.countryCodes] field)
- * * `/single_option` — poll with just 1 option (minimum options count decreased from 2 to 1)
- *
- * [onPollUpdates] prints [dev.inmo.tgbotapi.types.polls.Poll.media], [dev.inmo.tgbotapi.types.polls.Poll.membersOnly],
- * [dev.inmo.tgbotapi.types.polls.Poll.countryCodes], [QuizPoll.explanationMedia], and
- * [dev.inmo.tgbotapi.types.polls.PollOption.media] for each option.
+ * The first element of [args] must be the bot token. An optional exact `debug`
+ * value in any later position enables diagnostic logging. The registered commands
+ * create regular polls and quizzes with anonymity, media, audience restrictions,
+ * custom emoji, and single-option variants; update handlers report answers, state
+ * changes, option edits, and replies associated with poll options.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
@@ -312,6 +304,30 @@ suspend fun main(vararg args: String) {
             }
         }
 
+        // Demonstrates TelegramMediaLink (InputMediaLink, Bot API 10.1) as poll option media.
+        // Link is the only new poll media type in 10.1 and is allowed only as InputPollOptionMedia.
+        onCommand("link_poll") {
+            val sentPoll = sendRegularPoll(
+                it.chat.id,
+                buildEntities { regular("Pick your favourite resource") },
+                listOf(
+                    // InputPollOptionMedia via TelegramMediaLink (InputMediaLink)
+                    InputPollOption(
+                        media = TelegramMediaLink("https://core.telegram.org/bots/api")
+                    ) { regular("Bot API docs") },
+                    InputPollOption(
+                        media = TelegramMediaLink("https://github.com/InsanusMokrassar/ktgbotapi")
+                    ) { regular("ktgbotapi") },
+                    InputPollOption { regular("None of these") },
+                ),
+                isAnonymous = false,
+                replyParameters = ReplyParameters(it)
+            )
+            pollToChatMutex.withLock {
+                pollToChat[sentPoll.content.poll.id] = sentPoll.chat.id
+            }
+        }
+
         onPollAnswer {
             val chatId = pollToChat[it.pollId] ?: return@onPollAnswer
 
@@ -380,6 +396,7 @@ suspend fun main(vararg args: String) {
             BotCommand("members_only", "Poll restricted to channel members only (membersOnly)"),
             BotCommand("country_codes", "Poll targeted to US, DE, JP users (countryCodes)"),
             BotCommand("single_option", "Poll with 1 option (minimum is now 1, not 2)"),
+            BotCommand("link_poll", "Poll with link media (TelegramMediaLink) on options"),
         )
 
         allUpdatesFlow.subscribeLoggingDropExceptions(scope = this) {

README.md

@@ -1,34 +1,69 @@
-# TelegramBotAPI-examples
+# TelegramBotAPI examples
 
-This repository contains several examples of simple bots which are using TelegramBotAPI
+Runnable examples for [TelegramBotAPI](https://github.com/InsanusMokrassar/TelegramBotAPI). Each module focuses on a small Telegram Bot API feature and has its own README with detailed behavior, setup, permissions, and optional arguments.
 
-## How to use this repository
+## Running an example
 
-***TO RUN NATIVE TARGETS ON LINUX YOU SHOULD INSTALL CURL LIBRARY. FOR EXAMPLE: `sudo apt install libcurl4-gnutls-dev`***
+Run commands from the repository root and replace placeholders such as `<BOT_TOKEN>` and `<ADMIN_USER_ID>`. The table uses JVM launchers for multiplatform modules; their module READMEs also document browser and native targets where available.
 
-This repository contains several important things:
+The shortcuts include all mode tokens supported by each launcher. Remove `debug` to disable verbose logging and remove `testServer` to use Telegram's production Bot API. These are positional values inside `--args` and intentionally have no leading dashes: the current launchers recognize `debug`, not `--debug`, and `testServer`, not `--testServer`.
 
-* Example subprojects
-* Commits
-* Structure
+Native targets on Linux require libcurl development files, for example:
 
-### Example subproject
+```bash
+sudo apt install libcurl4-gnutls-dev
+```
 
-Each example subproject contains information about how to run this example and what is it
-doing. Usually, it is some simple thing like sending "hello" message to the user which
-wrote to the bot.
+## Modules
 
-### Commits
+| Module | What it demonstrates | Launch shortcut |
+| --- | --- | --- |
+| [BoostsInfoBot](BoostsInfoBot/) | Requests a channel, lists the requesting user's boosts, and logs boost updates. | `./gradlew :BoostsInfoBot:run --args="<BOT_TOKEN> debug"` |
+| [BotSubscriptionsBot](BotSubscriptionsBot/) | Observes recurring Telegram Stars subscription state updates. | `./gradlew :BotSubscriptionsBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [BusinessConnectionsBot](BusinessConnectionsBot/) | Manages a connected Business account, messages, Stars, gifts, stories, and checklists. | `./gradlew :BusinessConnectionsBot:run --args="<BOT_TOKEN> debug"` |
+| [ChatAvatarSetter](ChatAvatarSetter/) | Sets a chat photo from an image sent to the bot. | `./gradlew :ChatAvatarSetter:run --args="<BOT_TOKEN>"` |
+| [ChatManagementBot](ChatManagementBot/) | Exercises member permissions, administrator queries, reaction deletion, and bot-to-bot messages. | `./gradlew :ChatManagementBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [ChecklistsBot](ChecklistsBot/) | Receives and renders checklist messages and checklist service events. | `./gradlew :ChecklistsBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [CommunitiesBot](CommunitiesBot/) | Handles community join/leave events and inspects a chat's current community. | `./gradlew :CommunitiesBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [CustomBot](CustomBot/) | Provides a diagnostics playground for contexts, request logging, profile audio, and Stars balance. | `./gradlew :CustomBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [DeepLinksBot](DeepLinksBot/) | Generates bot deep links and consumes their start payloads. | `./gradlew :DeepLinksBot:run --args="<BOT_TOKEN>"` |
+| [DraftsBot](DraftsBot/) † | Streams message drafts before sending the completed message. | `./gradlew :DraftsBot:run --args="<BOT_TOKEN>"` |
+| [EphemeralMessagesBot](EphemeralMessagesBot/) | Sends ephemeral messages revealed through an inline button. | `./gradlew :EphemeralMessagesBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [FSMBot](FSMBot/) | Implements a conversational finite-state machine with chat-scoped in-memory state. | `./gradlew :FSMBot:run --args="<BOT_TOKEN>"` |
+| [FilesLoaderBot](FilesLoaderBot/) | Downloads incoming media to disk and sends it back to the chat. | `./gradlew :FilesLoaderBot:run --args="<BOT_TOKEN> <OUTPUT_DIRECTORY>"` |
+| [ForwardInfoSenderBot](ForwardInfoSenderBot/) | Reports the forward-origin metadata of received content. | `./gradlew :ForwardInfoSenderBot:run --args="<BOT_TOKEN>"` |
+| [GiftsBot](GiftsBot/) | Paginates and lists gifts owned by a user or chat. | `./gradlew :GiftsBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [GiveawaysBot](GiveawaysBot/) | Logs giveaway creation, completion, and winner events. | `./gradlew :GiveawaysBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [GuestQueryBot](GuestQueryBot/) | Handles guest queries in chats where the bot is not a member. | `./gradlew :GuestQueryBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [HelloBot](HelloBot/) | Greets users, groups, channels, or business chats when mentioned. | `./gradlew :HelloBot:run --args="<BOT_TOKEN>"` |
+| [InlineQueriesBot](InlineQueriesBot/) | Answers inline queries and supplies a deep-link result. | `./gradlew :InlineQueriesBot:runJvm --args="<BOT_TOKEN>"` |
+| [JoinRequestQueriesBot](JoinRequestQueriesBot/) | Queues or approves join requests, optionally delegating the decision to a Web App. | `./gradlew :JoinRequestQueriesBot:run --args="<BOT_TOKEN> https://example.com/verify debug testServer"` |
+| [KeyboardsBot](KeyboardsBot/) | Demonstrates reply, inline, callback, paged, copy-text, and inline-mode keyboards. | `./gradlew :KeyboardsBot:jvm_launcher:run --args="<BOT_TOKEN> debug"` |
+| [LinkPreviewsBot](LinkPreviewsBot/) | Sends the same link using multiple link-preview configurations. | `./gradlew :LinkPreviewsBot:run --args="<BOT_TOKEN> debug"` |
+| [LiveLocationsBot](LiveLocationsBot/) | Sends, updates, cancels, and stops a live-location message. | `./gradlew :LiveLocationsBot:run --args="<BOT_TOKEN>"` |
+| [LivePhotosBot](LivePhotosBot/) | Receives, sends, groups, edits, and sells Telegram Live Photos. | `./gradlew :LivePhotosBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [ManagedBotsBot](ManagedBotsBot/) † | Creates and administers managed bots and inspects personal-channel messages. | `./gradlew :ManagedBotsBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [MemberUpdatedWatcherBot](MemberUpdatedWatcherBot/) | Logs and reports bot/member status transitions in chats. | `./gradlew :MemberUpdatedWatcherBot:run --args="<BOT_TOKEN> debug"` |
+| [MyBot](MyBot/) † | Replaces or removes the bot's global profile photo and prints diagnostics. | `./gradlew :MyBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [PollsBot](PollsBot/) † | Sends regular polls, quizzes, poll media, and handles poll updates. | `./gradlew :PollsBot:run --args="<BOT_TOKEN> debug"` |
+| [RandomFileSenderBot](RandomFileSenderBot/) | Picks random local files and sends them individually or as media groups. | `./gradlew :RandomFileSenderBot:runJvm --args="<BOT_TOKEN> <FILES_DIRECTORY>"` |
+| [ReactionsInfoBot](ReactionsInfoBot/) | Handles per-user reaction changes and anonymous reaction-count updates. | `./gradlew :ReactionsInfoBot:run --args="<BOT_TOKEN> debug"` |
+| [ResenderBot](ResenderBot/) | Recreates received content while preserving reply, quote, effect, and business context. | `./gradlew :ResenderBot:jvm_launcher:run --args="<BOT_TOKEN> debug"` |
+| [RichMessagesBot](RichMessagesBot/) | Demonstrates rich HTML/Markdown/blocks, streaming drafts, inline results, and media. | `./gradlew :RichMessagesBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [RightsChangerBot](RightsChangerBot/) | Uses an FSM and inline keyboards to change member and administrator rights. | `./gradlew :RightsChangerBot:run --args="<BOT_TOKEN> <ALLOWED_USER_ID> debug"` |
+| [SlotMachineDetectorBot](SlotMachineDetectorBot/) | Detects slot-machine dice and decodes their reel values. | `./gradlew :SlotMachineDetectorBot:run --args="<BOT_TOKEN>"` |
+| [StarTransactionsBot](StarTransactionsBot/) | Demonstrates Stars invoices, transaction history, paid media, and refunds. | `./gradlew :StarTransactionsBot:run --args="<BOT_TOKEN> <ADMIN_USER_ID> debug testServer"` |
+| [StickerInfoBot](StickerInfoBot/) † | Looks up sticker-set metadata for stickers and custom emoji. | `./gradlew :StickerInfoBot:jvm_launcher:run --args="<BOT_TOKEN>"` |
+| [StickerSetHandler](StickerSetHandler/) | Creates and manages a sticker set owned by each private-chat user. | `./gradlew :StickerSetHandler:run --args="<BOT_TOKEN>"` |
+| [SuggestedPosts](SuggestedPosts/) | Handles channel direct messages and the suggested-post lifecycle. | `./gradlew :SuggestedPosts:run --args="<BOT_TOKEN> debug testServer"` |
+| [TagsBot](TagsBot/) | Sets chat-member tags, delegates tag management, and reads sender tags. | `./gradlew :TagsBot:run --args="<BOT_TOKEN> debug testServer"` |
+| [TopicsHandling](TopicsHandling/) | Exercises forum-topic and private-chat-topic actions and events. | `./gradlew :TopicsHandling:run --args="<BOT_TOKEN>"` |
+| [UserChatShared](UserChatShared/) | Requests users or chats through reply keyboards and handles the shared results. | `./gradlew :UserChatShared:run --args="<BOT_TOKEN> debug"` |
+| [WebApp](WebApp/) | Serves a Compose Web client and demonstrates Telegram Web App integration. | `./gradlew :WebApp:runJvm --args="<BOT_TOKEN> https://webapp.example 8080 debug testServer"` |
+| [WebHooks](WebHooks/) | Receives Telegram updates through a Ktor webhook server instead of long polling. | `./gradlew :WebHooks:run --args="<BOT_TOKEN> https://bot.example.com debug"` |
 
-Commits can contains some things like migration onto new version (especially it is actual
-for major version changes), updates according to the new features in versions and
-different other things which usually more important in context of history or changes
-between library version
+† These modules currently contain a stale Gradle `mainClassName` mapping, documented in their module README. The shown command is the intended launch command but will not start until that mapping is corrected.
 
-### Structure
+## Repository as a reference
 
-Structure of this repository fully representative (it is the reason why this repo
-contains multiplatform subprojects) and you can use it as some template (but I am strongly
-recommend you to use my
-[TelegramBot template](https://github.com/InsanusMokrassar/TelegramBotAPI-bot_template) or
-[Multiplatform Project template](https://github.com/InsanusMokrassar/KotlinMultiplatformProjectTemplate))
+The example structure can be used as a starting point, and the commit history is useful for seeing migrations between TelegramBotAPI versions. For new projects, consider the [Telegram Bot template](https://github.com/InsanusMokrassar/TelegramBotAPI-bot_template) or [Kotlin Multiplatform Project template](https://github.com/InsanusMokrassar/KotlinMultiplatformProjectTemplate).

RandomFileSenderBot/README.md

@@ -1,9 +1,76 @@
 # RandomFileSenderBot
 
-This bot will send random file from input folder OR from bot working folder
+This Kotlin Multiplatform example sends randomly selected local files in response to a Telegram command. It uses long
+polling and can run on the JVM or as a Kotlin/Native executable.
 
-## Launch
+## Behavior
+
+The bot registers one command:
+
+- `/send_file` requests one file;
+- `/send_file N` requests `N` files when `N` is a positive integer; and
+- a missing or non-numeric count defaults to one. Zero and negative counts select nothing and receive
+  `Nothing selected :(`.
+
+For each requested file, the picker starts at the configured root. A file root is selected directly; a directory root
+is searched by choosing one random child at each level until a file is reached. This is not a uniform choice among all
+files in an uneven directory tree, and the same file may be selected more than once. Zero-byte files and unsuccessful
+selections are retried. Consequently, a positive request can keep retrying indefinitely when no non-empty file is
+reachable.
+
+One file is sent as a document. Multiple files are sent as document media groups, split at Telegram's maximum media
+group size. All sends enable Telegram's protected-content flag. The bot also prints its own account information at
+startup and prints polling exceptions.
+
+## Setup and security
+
+Create a bot with BotFather and obtain its token. Give the process read access to a dedicated directory containing only
+files that every bot user may receive, and pass that directory explicitly. The bot has no user or chat allowlist and no
+file-name or file-type filter; anyone able to send it the command can request files reachable through the configured
+tree. Protected content is not an access-control mechanism.
+
+Keep the token private. These launchers accept it on the command line, where it may be retained in shell history or be
+visible to other local processes. Also avoid roots containing secrets or links to locations outside the intended tree.
+
+## Arguments
+
+Both launchers interpret arguments in the same order:
+
+1. `BOT_TOKEN` (required). Omitting it fails immediately.
+2. `ROOT_PATH` (optional in code), either a file or directory. Relative paths are resolved from the process working
+   directory; use an explicit absolute path for predictable behavior. The launchers pass an empty path when this
+   argument is omitted, whose filesystem behavior differs by platform and is not a reliable working-directory default.
+
+Additional arguments are ignored.
+
+## Launch from the repository root
+
+### JVM
 
 ```bash
-../gradlew run --args="BOT_TOKEN[ optional/folder/path]"
+./gradlew :RandomFileSenderBot:runJvm --args="<BOT_TOKEN> /absolute/path/to/files"
 ```
+
+The JVM picker uses `java.io.File`. A missing, empty, or unreadable directory produces no selection and therefore causes
+a positive request to keep retrying.
+
+### Kotlin/Native
+
+The shared native configuration selects Linux x64, Linux Arm64, or Windows x64 for the current host. macOS is not
+configured. Link the debug executable with Gradle, then pass the arguments directly to the generated program:
+
+```bash
+./gradlew :RandomFileSenderBot:linkDebugExecutableNative
+./RandomFileSenderBot/build/bin/native/debugExecutable/RandomFileSenderBot.kexe "<BOT_TOKEN>" "/absolute/path/to/files"
+```
+
+On Windows, run
+`RandomFileSenderBot\build\bin\native\debugExecutable\RandomFileSenderBot.exe "<BOT_TOKEN>" "C:\path\to\files"`
+after the same Gradle link task. The native picker uses Okio; unlike the JVM picker, inaccessible or invalid paths may
+raise a filesystem exception that is printed by the polling exception handler.
+
+## Source sets
+
+- `commonMain` contains the picker contract and the long-polling bot behavior.
+- `jvmMain` implements recursive selection with `java.io.File` and provides the suspending JVM entry point.
+- `nativeMain` implements recursive selection with Okio and provides a `runBlocking` native entry point.

RandomFileSenderBot/src/commonMain/kotlin/Bot.kt

@@ -18,14 +18,18 @@ import dev.inmo.tgbotapi.types.mediaCountInMediaGroup
 
 private const val command = "send_file"
 
+/**
+ * Selects a file by recursively choosing random children below [currentRoot].
+ *
+ * @return the selected file, or `null` when the picker cannot continue from the current root
+ */
 expect fun pickFile(currentRoot: MPPFile): MPPFile?
 
 /**
- * This bot will send files inside of working directory OR from directory in the second argument.
- * You may send /send_file command to this bot to get random file from the directory OR
- * `/send_file $number` when you want to receive required number of files. For example,
- * /send_file and `/send_file 1` will have the same effect - bot will send one random file.
- * But if you will send `/send_file 5` it will choose 5 random files and send them as group
+ * Runs the long-polling random-file bot using [token] and serving selections rooted at [folder].
+ *
+ * `/send_file` selects one non-empty file, while `/send_file N` selects `N` files and splits them into valid Telegram
+ * media-group sizes.
  */
 suspend fun doRandomFileSenderBot(token: String, folder: MPPFile) {
     val bot = telegramBot(token)

RandomFileSenderBot/src/jvmMain/kotlin/ActualPickFile.kt

@@ -1,6 +1,7 @@
 import dev.inmo.micro_utils.common.MPPFile
 import java.io.File
 
+/** JVM picker backed by [File], returning a file root directly or descending through random directory children. */
 actual fun pickFile(currentRoot: MPPFile): File? {
     if (currentRoot.isFile) {
         return currentRoot

RandomFileSenderBot/src/jvmMain/kotlin/RandomFileSenderBot.kt

@@ -1,5 +1,6 @@
 import dev.inmo.micro_utils.common.MPPFile
 
+/** JVM entry point; [args] contains the bot token followed by an optional picker root. */
 suspend fun main(args: Array<String>) {
     doRandomFileSenderBot(args.first(), MPPFile(args.getOrNull(1) ?: ""))
 }

RandomFileSenderBot/src/nativeMain/kotlin/ActualPickFile.kt

@@ -1,6 +1,7 @@
 import dev.inmo.micro_utils.common.MPPFile
 import okio.FileSystem
 
+/** Native picker backed by Okio, returning a file root directly or descending through random directory children. */
 actual fun pickFile(currentRoot: MPPFile): MPPFile? {
     if (FileSystem.SYSTEM.exists(currentRoot) && FileSystem.SYSTEM.listOrNull(currentRoot) == null) {
         return currentRoot

RandomFileSenderBot/src/nativeMain/kotlin/RandomFileSenderBot.kt

@@ -1,6 +1,7 @@
 import kotlinx.coroutines.runBlocking
 import okio.Path.Companion.toPath
 
+/** Kotlin/Native entry point; [args] contains the bot token followed by an optional picker root. */
 fun main(args: Array<String>) {
     runBlocking {
         doRandomFileSenderBot(args.first(), args.getOrNull(1) ?.toPath() ?: "".toPath())

ReactionsInfoBot/README.md

@@ -1,9 +1,44 @@
 # ReactionsInfoBot
 
-This bot will send info about user reactions in his PM with reply to message user reacted to
+A long-polling example that handles Telegram's per-user reaction updates and anonymous reaction-count updates. It has no commands and does not respond to ordinary messages.
+
+## Behavior
+
+When an identifiable user changes their reactions on a message, the bot:
+
+1. temporarily adds a `✍` reaction to the original message;
+2. sends that user a private message which externally replies to the reacted message;
+3. lists the user's new reaction set, including ordinary emoji, rendered custom emoji with its custom-emoji ID, a generic label for paid reactions, and fallback information for unknown reaction types;
+4. removes its temporary reaction after the private reply succeeds.
+
+If the user removed all reactions, the private message contains only its heading. Updates where a chat is the reaction actor are not handled by this per-user trigger. Telegram also does not deliver reaction-change updates caused by bots, so the temporary `✍` reaction does not trigger this handler recursively.
+
+For anonymous reaction-count updates, the bot fetches and prints the extended chat plus the raw count update to standard output. It does not send a Telegram message for those updates, which Telegram may deliver after a delay.
+
+If adding `✍` is not allowed, the private-message step is not reached. If the private message fails, the final cleanup is not reached and the bot's temporary reaction can remain on the original message.
+
+## Telegram setup, permissions, and privacy
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- Add the bot to each group, supergroup, or channel to watch and promote it to administrator. Telegram requires administrator status for both `message_reaction` and `message_reaction_count` updates; the long-polling setup explicitly requests these update types.
+- Enable reactions in the watched chat and allow the `✍` emoji so the bot can apply its temporary marker.
+- Each user who should receive reports must first open the bot's private chat and press **Start**. The bot has no `/start` response, but Telegram otherwise prevents it from initiating a private conversation. Reports also fail if the user blocks the bot.
+- BotFather privacy mode may remain enabled. It controls group-message delivery, not reaction updates.
+
+The example uses long polling and automatically removes an existing webhook at startup. Run only one update consumer for the token at a time.
+
+## Arguments
+
+The first argument is the required bot token. Debug logging is enabled only when the second argument is exactly `debug`; later occurrences are ignored.
 
 ## Launch
 
+From the repository root:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :ReactionsInfoBot:run --args="<BOT_TOKEN>"
+```
+
+```bash
+./gradlew :ReactionsInfoBot:run --args="<BOT_TOKEN> debug"
 ```

ReactionsInfoBot/src/main/kotlin/ReactionsInfoBot.kt

@@ -15,7 +15,12 @@ import dev.inmo.tgbotapi.utils.customEmoji
 import dev.inmo.tgbotapi.utils.regular
 
 /**
- * This bot will send info about user reactions in his PM with reply to message user reacted to
+ * Runs the ReactionsInfoBot example using long polling.
+ *
+ * User-attributed reaction changes are reported to the reacting user in a private cross-chat reply, with a temporary
+ * `✍` reaction marking the source message. Anonymous reaction-count updates are printed to standard output.
+ *
+ * @param args the bot token first and, optionally, `debug` as the second element to enable formatted KSLog output
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

ResenderBot/README.md

@@ -0,0 +1,75 @@
+# ResenderBot
+
+A multiplatform long-polling example that recreates received content in the same
+chat. Shared behavior lives in `ResenderBotLib`; JVM, browser/JS, and native entry
+points start it in platform-specific ways.
+
+## Resend behavior
+
+The bot defines no commands. For each content message, it shows a typing action and
+uses `createResend` to send equivalent content back to the originating chat. When
+present, it carries over the replied-to message metadata, text quote entities and
+position, and the message effect ID.
+
+Business content sent by the business-connection owner is ignored; other delivered
+content messages are eligible. Processing is separated by chat. The bot prints each
+received update and each resend result, and reports its `getMe` result through the
+launcher's output callback.
+
+## Source sets and launchers
+
+- `ResenderBotLib/commonMain` provides the public `activateResenderBot` function and
+  all Telegram handlers for JVM, JS, and native consumers.
+- `ResenderBotLib/jsMain` provides a browser form. Each submission starts another
+  bot and displays callback output in its own page element; console output remains
+  in the browser developer tools.
+- `jvm_launcher` provides a suspending CLI entry point and optional debug logging.
+- `native_launcher` wraps the shared suspending function in `runBlocking`. Its
+  shared native template selects Linux x64/Arm64 or Windows x64 for the host.
+
+## Setup and permissions
+
+Create a bot, obtain its token, and keep it private. Start a private chat with the
+bot or add it to a chat where Telegram will deliver the desired content. The bot
+must be allowed to send each content type it should reproduce; no administrator-only
+methods are used. Long polling is used, so run only one launcher per token.
+
+The browser form handles the token in client-side code and uses a plain text input.
+Use it only on a trusted local page, submit once, and close the page when finished.
+Linux native builds also require the repository's documented libcurl dependency.
+
+## Run from the repository root
+
+### JVM
+
+The first argument is the required token. `debug` is recognized only as the second
+argument; later arguments are ignored.
+
+```bash
+./gradlew :ResenderBot:jvm_launcher:run --args="BOT_TOKEN"
+./gradlew :ResenderBot:jvm_launcher:run --args="BOT_TOKEN debug"
+```
+
+### Browser/JS
+
+```bash
+./gradlew :ResenderBot:ResenderBotLib:jsBrowserDevelopmentRun
+```
+
+Enter the token in the page form and select **Start bot**. There are no browser
+command-line arguments.
+
+### Kotlin/Native
+
+Build the host-specific debug executable, then pass the required token directly to
+it. Additional native arguments are ignored.
+
+```bash
+./gradlew :ResenderBot:native_launcher:linkDebugExecutableNative
+./ResenderBot/native_launcher/build/bin/native/debugExecutable/native_launcher.kexe "BOT_TOKEN"
+```
+
+On Windows, run
+`ResenderBot\\native_launcher\\build\\bin\\native\\debugExecutable\\native_launcher.exe "BOT_TOKEN"`
+after the same Gradle link task. macOS hosts are not configured by the native
+launcher template.

ResenderBot/ResenderBotLib/src/commonMain/kotlin/ResenderBot.kt

@@ -20,6 +20,16 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.currentCoroutineContext
 
+/**
+ * Starts the shared long-polling resender and suspends until polling stops.
+ *
+ * Eligible content is recreated in its source chat with reply/quote metadata and
+ * message effects preserved. Business messages sent by the business-connection
+ * owner are skipped.
+ *
+ * @param token bot token used for polling and API requests.
+ * @param print output callback for bot information and resend diagnostics.
+ */
 suspend fun activateResenderBot(
     token: String,
     print: (Any) -> Unit

ResenderBot/ResenderBotLib/src/jsMain/kotlin/ResenderBot.kt

@@ -4,6 +4,10 @@ import org.w3c.dom.*
 
 private val scope = CoroutineScope(Dispatchers.Default)
 
+/**
+ * Installs the browser token form and starts one resender for each submission.
+ * Callback output from each instance is displayed in its associated page element.
+ */
 fun main() {
     document.addEventListener(
         "DOMContentLoaded",

ResenderBot/jvm_launcher/src/main/kotlin/ResenderBotJvm.kt

@@ -3,6 +3,12 @@ import dev.inmo.kslog.common.LogLevel
 import dev.inmo.kslog.common.defaultMessageFormatter
 import dev.inmo.kslog.common.setDefaultKSLog
 
+/**
+ * Starts the JVM resender launcher.
+ *
+ * [args] must contain the bot token first. An optional exact `debug` value in the
+ * second position enables diagnostic logging; later elements are ignored.
+ */
 suspend fun main(args: Array<String>) {
     val isDebug = args.getOrNull(1) == "debug"
 

ResenderBot/native_launcher/src/nativeMain/kotlin/ResenderBot.kt

@@ -1,5 +1,9 @@
 import kotlinx.coroutines.runBlocking
 
+/**
+ * Starts the native resender launcher with the first element of [args] as its bot
+ * token. Later elements are ignored.
+ */
 fun main(vararg args: String) {
     runBlocking {
         activateResenderBot(args.first()) {

RichMessagesBot/README.md

@@ -0,0 +1,97 @@
+# RichMessagesBot
+
+RichMessagesBot is a long-polling showcase of Telegram rich messages. It sends
+rich content from HTML, Markdown, and the typed `InputRichMessageBlocks` DSL;
+streams drafts; edits rich text; handles incoming rich messages; and supplies
+rich content from inline and guest queries.
+
+## Commands
+
+The bot installs seven commands in Telegram's default command menu. Three
+additional handlers can be invoked by typing their commands manually.
+
+| Command | In menu | Demonstration |
+| --- | --- | --- |
+| `/rich_html` | Yes | Sends the full HTML fixture: inline styles and links, references, emoji and time links, math, headings, lists and checkboxes, quotations, remote media and maps, collages, slideshows, tables, details, and captions. |
+| `/rich_markdown` | Yes | Sends and logs the corresponding Markdown fixture, including remote photo, video, audio, voice-note, animation, collage, and slideshow markup. |
+| `/rich_markdown_medialess` | No | Sends and logs the Markdown fixture without media, collages, or slideshows. |
+| `/rich_markdown_blocks` | No | Sends and logs the full fixture as a typed block tree, including first-class media blocks, captions, collages, and slideshows. |
+| `/rich_markdown_medialess_blocks` | No | Sends and logs the same typed block tree without its media section. |
+| `/rich_blocks` | Yes | Sends a smaller, directly constructed block tree with headings, formatted paragraphs, ordered and unordered checkbox lists, a divider, preformatted Kotlin, and a quotation. |
+| `/rich_draft` | Yes | Streams three Markdown revisions under draft ID `1`, one second apart, then sends a normal final rich message. |
+| `/rich_blocks_draft` | Yes | Streams two draft-only `thinking()` blocks under draft ID `2`, one second apart, then sends a normal typed-block answer. |
+| `/rich_edit` | Yes | Sends a Markdown rich message, waits two seconds, and replaces its rich content with `EditChatMessageRichText`. |
+| `/wait_rich` | Yes | Prompts for a rich message, waits for the next matching content, and reports its block count. |
+
+The two draft examples finalize by sending a new normal rich message; they do not
+turn the draft itself into the final message. They use distinct fixed IDs (`1`
+and `2`); concurrent runs of the same command in one chat reuse that command's
+ID.
+
+## Other triggers
+
+| Trigger | Behavior |
+| --- | --- |
+| Any photo | Reuses the received Telegram file ID without downloading it. The bot first sends HTML whose `tg://photo?id=userphoto` reference is resolved by `InputRichMessageMedia`, then sends the same photo as a typed `photo()` block. |
+| Any incoming rich message | Logs right-to-left state and every parsed block, replies with the block count, and resends the rich message with `createResend`. The `onlyRichMessageContentMessages` flow also logs its block count. |
+| Any inline query | Returns uncached HTML and Markdown articles whose selected messages use `InputRichMessageContent`. |
+| A text guest request containing `/rich_guest` | Returns one inline article containing the full Markdown fixture. This is a substring check, not a registered bot command. Non-text guest requests and text without that exact case-sensitive substring are ignored by this handler. |
+
+Every received update is also printed to standard output. A rich message received
+while `/wait_rich` is active can therefore be observed by the waiter, the general
+rich-message trigger, and the filtered update flow.
+
+## Media notes
+
+The built-in HTML and Markdown fixtures refer to public files under
+`https://telegram.org/example/`. The typed full fixture constructs Telegram media
+from the same URLs. The photo trigger instead demonstrates reusing an existing
+Telegram file ID and assigning an alias for a `tg://photo?id=...` reference.
+
+The source also shows the two library shapes used for rich media: an
+`InputRichMessageMedia` mapping for markup references and first-class photo,
+video, audio, voice-note, animation, collage, and slideshow blocks. The library
+can collect multipart files nested in a rich-message tree as `attach://` uploads,
+although this example's running handlers use URLs or an existing file ID.
+
+## Telegram setup and permissions
+
+1. Create a bot with BotFather and obtain its token. Keep the token out of source
+   control.
+2. Start a private chat with the bot, or add it to a chat and allow it to send
+   messages and media.
+3. To test ordinary photo and rich-message triggers in a group, ensure Telegram
+   delivers non-command messages to the bot, for example by disabling Group
+   Privacy Mode or making the bot an administrator.
+4. Enable Inline Mode in BotFather to exercise the inline-query results.
+5. Enable guest queries for the bot to exercise the `/rich_guest` guest-request
+   path. The bot does not need to be a member of the target chat for that path.
+
+No handler requires an administrator-only Bot API method. The program does not
+configure a webhook or validate chat permissions before making requests.
+
+## Arguments
+
+The first program argument is required and is always treated as the bot token.
+Optional flags are exact and case-sensitive, may follow the token in either
+order, and unknown later arguments are ignored.
+
+| Argument | Effect |
+| --- | --- |
+| `<BOT_TOKEN>` | Token used to create the bot. Omitting it fails before polling starts. |
+| `debug` | Enables formatted KSLog diagnostics on standard output. |
+| `testServer` | Connects to Telegram's Bot API test environment. |
+
+## Run
+
+From the repository root:
+
+```bash
+./gradlew :RichMessagesBot:run --args="<BOT_TOKEN>"
+```
+
+For example, with both optional flags:
+
+```bash
+./gradlew :RichMessagesBot:run --args="<BOT_TOKEN> debug testServer"
+```

RichMessagesBot/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'kotlin'
+apply plugin: 'application'
+
+mainClassName="RichMessagesBotKt"
+
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    implementation "dev.inmo:tgbotapi:$telegram_bot_api_version"
+}

RichMessagesBot/src/main/kotlin/RichMessagesBot.kt

@@ -0,0 +1,926 @@
+import dev.inmo.kslog.common.KSLog
+import dev.inmo.kslog.common.LogLevel
+import dev.inmo.kslog.common.defaultMessageFormatter
+import dev.inmo.kslog.common.setDefaultKSLog
+import dev.inmo.micro_utils.coroutines.subscribeLoggingDropExceptions
+import dev.inmo.tgbotapi.extensions.api.answers.answer
+import dev.inmo.tgbotapi.extensions.api.bot.setMyCommands
+import dev.inmo.tgbotapi.extensions.api.send.reply
+import dev.inmo.tgbotapi.extensions.api.send.sendRichMessage
+import dev.inmo.tgbotapi.extensions.api.send.sendRichMessageDraft
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitRichMessage
+import dev.inmo.tgbotapi.extensions.behaviour_builder.telegramBotWithBehaviourAndLongPolling
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onBaseInlineQuery
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommand
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onGuestRequestMessage
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onPhoto
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onRichMessage
+import dev.inmo.tgbotapi.extensions.utils.baseSentMessageUpdateOrNull
+import dev.inmo.tgbotapi.extensions.utils.contentMessageOrNull
+import dev.inmo.tgbotapi.extensions.utils.onlyRichMessageContentMessages
+import dev.inmo.tgbotapi.extensions.utils.withContentOrNull
+import dev.inmo.tgbotapi.requests.edit.text.EditChatMessageRichText
+import dev.inmo.tgbotapi.requests.abstracts.InputFile
+import dev.inmo.tgbotapi.types.BotCommand
+import dev.inmo.tgbotapi.types.CustomEmojiId
+import dev.inmo.tgbotapi.types.InlineQueries.InlineQueryResult.InlineQueryResultArticle
+import dev.inmo.tgbotapi.types.InlineQueries.InputMessageContent.InputRichMessageContent
+import dev.inmo.tgbotapi.types.InlineQueryId
+import dev.inmo.tgbotapi.types.TelegramDate
+import dev.inmo.tgbotapi.types.message.content.TextContent
+import dev.inmo.tgbotapi.types.message.textsources.BotCommandTextSource
+import dev.inmo.tgbotapi.types.media.TelegramMediaAnimation
+import dev.inmo.tgbotapi.types.media.TelegramMediaAudio
+import dev.inmo.tgbotapi.types.media.TelegramMediaPhoto
+import dev.inmo.tgbotapi.types.media.TelegramMediaVideo
+import dev.inmo.tgbotapi.types.media.TelegramMediaVoiceNote
+import dev.inmo.tgbotapi.types.rich.InputRichMessage
+import dev.inmo.tgbotapi.types.rich.InputRichMessageBlocks
+import dev.inmo.tgbotapi.types.rich.InputRichMessageHTML
+import dev.inmo.tgbotapi.types.rich.InputRichMessageMarkdown
+import dev.inmo.tgbotapi.types.rich.InputRichMessageMedia
+import dev.inmo.tgbotapi.types.rich.RichBlockCaption
+import dev.inmo.tgbotapi.types.rich.RichBlockTableCellAlign
+import dev.inmo.tgbotapi.types.rich.RichBlockTableCellVAlign
+import dev.inmo.tgbotapi.types.rich.RichTextPlain
+import dev.inmo.tgbotapi.types.rich.buildRichText
+import dev.inmo.tgbotapi.types.toChatId
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.mapNotNull
+
+/**
+ * Runs a long-polling showcase of the rich-message APIs introduced in Telegram Bot API 10.1 and 10.2.
+ *
+ * Outgoing [dev.inmo.tgbotapi.types.rich.InputRichMessage] values use one of three representations:
+ * [InputRichMessageHTML], [InputRichMessageMarkdown], or a typed [InputRichMessageBlocks] tree of
+ * [dev.inmo.tgbotapi.types.rich.InputRichBlock] values. The handlers demonstrate [sendRichMessage],
+ * [sendRichMessageDraft] revisions sharing a draft ID (including draft-only `thinking()` blocks), and edits
+ * through [EditChatMessageRichText]. Media is shown both as [InputRichMessageMedia] references such as
+ * `tg://photo?id=...` and as typed blocks; [dev.inmo.tgbotapi.requests.send.SendRichMessage] also turns
+ * multipart files inside an input tree into `attach://` uploads.
+ *
+ * Incoming [dev.inmo.tgbotapi.types.message.content.RichMessageContent] and user-selected content covers
+ * [onRichMessage], [waitRichMessage], [onlyRichMessageContentMessages], photo reuse, and
+ * [InputRichMessageContent] in inline and guest-query results. Parsed content is exposed as a
+ * [dev.inmo.tgbotapi.types.rich.RichMessage] containing [dev.inmo.tgbotapi.types.rich.RichBlock]s.
+ *
+ * @param args the bot token followed by optional, case-sensitive `debug` and `testServer` flags. The token
+ * must be present; unrecognized later arguments are ignored.
+ */
+suspend fun main(vararg args: String) {
+    val botToken = args.first()
+    val isDebug = args.any { it == "debug" }
+    val isTestServer = args.any { it == "testServer" }
+
+    if (isDebug) {
+        setDefaultKSLog(
+            KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
+                println(defaultMessageFormatter(level, tag, message, throwable))
+            }
+        )
+    }
+
+    val testMarkdownText = """
+        **bold text**
+        __bold text__
+        *italic text*
+        _italic text_
+        ~~strikethrough text~~
+        `inline fixed-width code`
+        ==marked text==
+        ||spoiler||
+
+        [inline URL](https://t.me/)
+        [inline e-mail](mailto:user@example.com)
+        [inline phone number](tel:+123456789)
+        [inline mention of a user](tg://user?id=123456789)
+        ![👍](tg://emoji?id=5368324170671202286)
+        ![22:45 tomorrow](tg://time?unix=1647531900&format=wDT)
+        ${'$'}x^2 + y^2$
+        \#hashtag ${'$'}USD +12345678901, card: 4242 4242 4242 4242, https://t.me t.me a@t.me /command @username
+        all the text above was on the same line
+
+        # Heading 1
+        ## Heading 2
+        ### Heading 3
+        #### Heading 4
+        ##### Heading 5
+        ###### Heading 6
+
+        Paragraph text
+
+        ```python
+          print('pre-formatted fixed-width code block written in the Python programming language')
+        ```
+
+        ---
+
+        - unordered list item
+        * unordered list item
+        + unordered list item
+
+        1. ordered list item
+        2. ordered list item
+
+        - [ ] task list item
+        - [x] completed task list item
+
+        >Block quotation started
+        >
+        >Block quotation continued on the next line
+        >Block quotation continued on the same line
+        >
+        >The last line of the block quotation
+
+        ![](https://telegram.org/example/photo.jpg)
+        ![](https://telegram.org/example/video.mp4)
+        ![](https://telegram.org/example/audio.mp3)
+        ![](https://telegram.org/example/audio.ogg)
+        ![](https://telegram.org/example/animation.gif)
+
+        ![](https://telegram.org/example/photo.jpg "Photo caption")
+        ![](https://telegram.org/example/video.mp4 "Video caption")
+        ![](https://telegram.org/example/audio.mp3 "Audio caption")
+        ![](https://telegram.org/example/audio.ogg "Voice note caption")
+        ![](https://telegram.org/example/animation.gif "Animation caption")
+
+        | Header 1 | Header 2 |
+        |:---------|:--------:|
+        | left     | center   |
+
+        Text with a reference[^id1] and another one[^id2].
+
+        [^id1]: Definition of the first footnote.
+        [^id2]: Definition of the second footnote.
+
+        $${'$'}E = mc^2$$
+
+        ```math
+        E = mc^2
+        ```
+
+        ## Example Nested Syntax Report for _Q1_
+        Intro with <u>underlined text</u>, ==marked text==, and ${'$'}x^2 + y^2$.
+        **Bold _italic <u>underlined italic bold</u> italic_ bold**
+        <u>In inline tags, nested **markdown** is parsed</u>
+        >Quote with **bold text, ~~strikethrough, and <tg-spoiler>spoiler</tg-spoiler>~~**, plus [a link](https://t.me/).
+
+        - List item with `code`, <sup>superscript</sup>, <sub>subscript</sub>, and a footnote[^note]
+        - Another item with **bold <tg-spoiler><code>spoiler code</code></tg-spoiler>**
+        - Another item with ~~strikethrough and <ins>inserted text</ins>~~
+
+        | Metric | Value |
+        |:-------|------:|
+        | Speed  | **42** <sup>ms</sup> |
+        | Status | <tg-spoiler>ready</tg-spoiler> |
+
+        [^note]: Footnote with _italic text_ and <u>HTML underline</u>.
+
+        ---
+
+        # Details blocks can contain Markdown content:
+
+        <details open><summary>Summary with **bold text**</summary>
+
+        ### Details heading
+        - List item with _italic text_
+        - List item with <tg-spoiler>spoiler</tg-spoiler>
+
+        </details>
+
+        # Collages and slideshows can contain Markdown media blocks:
+
+        <tg-collage>
+
+        ![](https://telegram.org/example/photo.jpg)
+        ![](https://telegram.org/example/video.mp4)
+
+        </tg-collage>
+
+        <tg-slideshow>
+
+        ![](https://telegram.org/example/photo.jpg)
+        ![](https://telegram.org/example/video.mp4)
+
+        </tg-slideshow>
+    """.trimIndent()
+    val testMarkdownMediaLessText = """
+        **bold text**
+        __bold text__
+        *italic text*
+        _italic text_
+        ~~strikethrough text~~
+        `inline fixed-width code`
+        ==marked text==
+        ||spoiler||
+
+        [inline URL](https://t.me/)
+        [inline e-mail](mailto:user@example.com)
+        [inline phone number](tel:+123456789)
+        [inline mention of a user](tg://user?id=123456789)
+        ![👍](tg://emoji?id=5368324170671202286)
+        ![22:45 tomorrow](tg://time?unix=1647531900&format=wDT)
+        ${'$'}x^2 + y^2$
+        \#hashtag ${'$'}USD +12345678901, card: 4242 4242 4242 4242, https://t.me t.me a@t.me /command @username
+        all the text above was on the same line
+
+        # Heading 1
+        ## Heading 2
+        ### Heading 3
+        #### Heading 4
+        ##### Heading 5
+        ###### Heading 6
+
+        Paragraph text
+
+        ```python
+          print('pre-formatted fixed-width code block written in the Python programming language')
+        ```
+
+        ---
+
+        - unordered list item
+        * unordered list item
+        + unordered list item
+
+        1. ordered list item
+        2. ordered list item
+
+        - [ ] task list item
+        - [x] completed task list item
+
+        >Block quotation started
+        >
+        >Block quotation continued on the next line
+        >Block quotation continued on the same line
+        >
+        >The last line of the block quotation
+
+        | Header 1 | Header 2 |
+        |:---------|:--------:|
+        | left     | center   |
+
+        Text with a reference[^id1] and another one[^id2].
+
+        [^id1]: Definition of the first footnote.
+        [^id2]: Definition of the second footnote.
+
+        $${'$'}E = mc^2$$
+
+        ```math
+        E = mc^2
+        ```
+
+        ## Example Nested Syntax Report for _Q1_
+        Intro with <u>underlined text</u>, ==marked text==, and ${'$'}x^2 + y^2$.
+        **Bold _italic <u>underlined italic bold</u> italic_ bold**
+        <u>In inline tags, nested **markdown** is parsed</u>
+        >Quote with **bold text, ~~strikethrough, and <tg-spoiler>spoiler</tg-spoiler>~~**, plus [a link](https://t.me/).
+
+        - List item with `code`, <sup>superscript</sup>, <sub>subscript</sub>, and a footnote[^note]
+        - Another item with **bold <tg-spoiler><code>spoiler code</code></tg-spoiler>**
+        - Another item with ~~strikethrough and <ins>inserted text</ins>~~
+
+        | Metric | Value |
+        |:-------|------:|
+        | Speed  | **42** <sup>ms</sup> |
+        | Status | <tg-spoiler>ready</tg-spoiler> |
+
+        [^note]: Footnote with _italic text_ and <u>HTML underline</u>.
+
+        ---
+
+        # Details blocks can contain Markdown content:
+
+        <details open><summary>Summary with **bold text**</summary>
+
+        ### Details heading
+        - List item with _italic text_
+        - List item with <tg-spoiler>spoiler</tg-spoiler>
+
+        </details>
+    """.trimIndent()
+    val testMarkdownMediaLessInputRichMessageBlocks = InputRichMessageBlocks {
+        paragraph {
+            bold("bold text")
+            plain("\n")
+            bold("bold text")
+            plain("\n")
+            italic("italic text")
+            plain("\n")
+            italic("italic text")
+            plain("\n")
+            strikethrough("strikethrough text")
+            plain("\n")
+            code("inline fixed-width code")
+            plain("\n")
+            marked("marked text")
+            plain("\n")
+            spoiler("spoiler")
+        }
+        paragraph {
+            url("inline URL", "https://t.me/")
+            plain("\n")
+            email("inline e-mail", "user@example.com")
+            plain("\n")
+            phone("inline phone number", "+123456789")
+            plain("\n")
+            url("inline mention of a user", "tg://user?id=123456789")
+            plain("\n")
+            customEmoji(CustomEmojiId("5368324170671202286"), "👍")
+            plain("\n")
+            dateTime("22:45 tomorrow", TelegramDate(1647531900L), "wDT")
+            plain("\n")
+            mathematicalExpression("x^2 + y^2")
+            plain("\n#hashtag ${'$'}USD +12345678901, card: 4242 4242 4242 4242, https://t.me t.me a@t.me /command @username\n")
+            plain("all the text above was on the same line")
+        }
+
+        h1("Heading 1")
+        h2("Heading 2")
+        h3("Heading 3")
+        h4("Heading 4")
+        h5("Heading 5")
+        h6("Heading 6")
+        paragraph("Paragraph text")
+        preformatted(
+            "  print('pre-formatted fixed-width code block written in the Python programming language')",
+            language = "python"
+        )
+        divider()
+
+        unorderedList {
+            item("unordered list item")
+            item("unordered list item")
+            item("unordered list item")
+        }
+        orderedList {
+            item(1) { paragraph("ordered list item") }
+            item(2) { paragraph("ordered list item") }
+        }
+        unorderedList {
+            item(hasCheckbox = true, isChecked = false) { paragraph("task list item") }
+            item(hasCheckbox = true, isChecked = true) { paragraph("completed task list item") }
+        }
+        blockQuotation {
+            paragraph("Block quotation started\nBlock quotation continued on the next line\nBlock quotation continued on the same line\nThe last line of the block quotation")
+        }
+
+        table {
+            row {
+                headerCell(align = RichBlockTableCellAlign.Left, valign = RichBlockTableCellVAlign.Top) { plain("Header 1") }
+                headerCell(align = RichBlockTableCellAlign.Center, valign = RichBlockTableCellVAlign.Middle) { plain("Header 2") }
+                headerCell(align = RichBlockTableCellAlign.Right, valign = RichBlockTableCellVAlign.Bottom) { plain("Header 2") }
+            }
+            row {
+                cell(align = RichBlockTableCellAlign.Left, valign = RichBlockTableCellVAlign.Top) { plain("left") }
+                cell(align = RichBlockTableCellAlign.Center, valign = RichBlockTableCellVAlign.Middle) { plain("center") }
+            }
+        }
+        paragraph {
+            plain("Text with a reference")
+            referenceLink("id1", "id1")
+            plain(" and another one")
+            referenceLink("id2", "id2")
+            plain(".")
+        }
+        paragraph { reference("Definition of the first footnote.", "id1") }
+        paragraph { reference("Definition of the second footnote.", "id2") }
+        mathematicalExpression("E = mc^2")
+        preformatted("E = mc^2", language = "math")
+
+        h2 {
+            plain("Example Nested Syntax Report for ")
+            italic("Q1")
+        }
+        paragraph {
+            plain("Intro with ")
+            underline("underlined text")
+            plain(", ")
+            marked("marked text")
+            plain(", and ")
+            mathematicalExpression("x^2 + y^2")
+            plain(".")
+        }
+        paragraph {
+            bold {
+                plain("Bold ")
+                italic {
+                    plain("italic ")
+                    underline("underlined italic bold")
+                    plain(" italic")
+                }
+                plain(" bold")
+            }
+        }
+        paragraph {
+            underline {
+                plain("In inline tags, nested ")
+                bold("markdown")
+                plain(" is parsed")
+            }
+        }
+        blockQuotation {
+            paragraph {
+                plain("Quote with ")
+                bold {
+                    plain("bold text, ")
+                    strikethrough {
+                        plain("strikethrough, and ")
+                        spoiler("spoiler")
+                    }
+                }
+                plain(", plus ")
+                url("a link", "https://t.me/")
+                plain(".")
+            }
+        }
+        unorderedList {
+            item {
+                paragraph {
+                    plain("List item with ")
+                    code("code")
+                    plain(", ")
+                    superscript("superscript")
+                    plain(", ")
+                    subscript("subscript")
+                    plain(", and a footnote")
+                    referenceLink("note", "note")
+                }
+            }
+            item {
+                paragraph {
+                    plain("Another item with ")
+                    bold { spoiler { code("spoiler code") } }
+                }
+            }
+            item {
+                paragraph {
+                    plain("Another item with ")
+                    strikethrough {
+                        plain("strikethrough and ")
+                        underline("inserted text")
+                    }
+                }
+            }
+        }
+        table {
+            row {
+                headerCell(align = RichBlockTableCellAlign.Left, valign = RichBlockTableCellVAlign.Middle) { plain("Metric") }
+                headerCell(align = RichBlockTableCellAlign.Right, valign = RichBlockTableCellVAlign.Middle) { plain("Value") }
+            }
+            row {
+                cell(align = RichBlockTableCellAlign.Left, valign = RichBlockTableCellVAlign.Middle) { plain("Speed") }
+                cell(align = RichBlockTableCellAlign.Right, valign = RichBlockTableCellVAlign.Middle) {
+                    bold("42")
+                    plain(" ")
+                    superscript("ms")
+                }
+            }
+            row {
+                cell(align = RichBlockTableCellAlign.Left, valign = RichBlockTableCellVAlign.Middle) { plain("Status") }
+                cell(align = RichBlockTableCellAlign.Right, valign = RichBlockTableCellVAlign.Middle) { spoiler("ready") }
+            }
+        }
+        paragraph {
+            reference("note") {
+                plain("Footnote with ")
+                italic("italic text")
+                plain(" and ")
+                underline("HTML underline")
+                plain(".")
+            }
+        }
+        divider()
+        h1("Details blocks can contain Markdown content:")
+        details(
+            summary = buildRichText {
+                plain("Summary with ")
+                bold("bold text")
+            },
+            isOpen = true
+        ) {
+            h3("Details heading")
+            unorderedList {
+                item { paragraph { plain("List item with "); italic("italic text") } }
+                item { paragraph { plain("List item with "); spoiler("spoiler") } }
+            }
+        }
+    }
+    val testMarkdownInputRichMessageBlocks = InputRichMessageBlocks {
+        testMarkdownMediaLessInputRichMessageBlocks.blocks.orEmpty().forEach(::add)
+
+        val photo = TelegramMediaPhoto(InputFile.fromUrl("https://telegram.org/example/photo.jpg"))
+        val video = TelegramMediaVideo(InputFile.fromUrl("https://telegram.org/example/video.mp4"))
+        val audio = TelegramMediaAudio(InputFile.fromUrl("https://telegram.org/example/audio.mp3"))
+        val voiceNote = TelegramMediaVoiceNote(InputFile.fromUrl("https://telegram.org/example/audio.ogg"))
+        val animation = TelegramMediaAnimation(InputFile.fromUrl("https://telegram.org/example/animation.gif"))
+
+        photo(photo)
+        video(video)
+        audio(audio)
+        voiceNote(voiceNote)
+        animation(animation)
+
+        photo(photo, RichBlockCaption(RichTextPlain("Photo caption")))
+        video(video, RichBlockCaption(RichTextPlain("Video caption")))
+        audio(audio, RichBlockCaption(RichTextPlain("Audio caption")))
+        voiceNote(voiceNote, RichBlockCaption(RichTextPlain("Voice note caption")))
+        animation(animation, RichBlockCaption(RichTextPlain("Animation caption")))
+
+        collage {
+            photo(photo)
+            video(video)
+        }
+        collage(RichBlockCaption(RichTextPlain("Collage caption"))) {
+            video(video)
+            photo(photo)
+        }
+        slideshow {
+            photo(photo)
+            video(video)
+        }
+        slideshow(RichBlockCaption(RichTextPlain("Slideshow caption"))) {
+            video(video)
+            photo(photo)
+        }
+    }
+
+    telegramBotWithBehaviourAndLongPolling(
+        botToken,
+        CoroutineScope(Dispatchers.IO),
+        testServer = isTestServer
+    ) {
+        // sendRichMessage with HTML-formatted content
+        onCommand("rich_html") {
+            sendRichMessage(
+                it.chat.id,
+                // InputRichMessageHTML factory — content described using HTML formatting
+                InputRichMessageHTML(
+                    """
+                        <a name="chapter-0"></a>
+                        <b>bold text</b>, <strong>bold text</strong>
+                        <i>italic text</i>, <em>italic text</em>
+                        <u>underlined text</u>, <ins>underlined text</ins>
+                        <s>strikethrough text</s>, <strike>strikethrough text</strike>, <del>strikethrough text</del>
+                        <code>inline fixed-width code</code>
+                        <mark>marked text</mark>
+                        <sub>subscript text</sub>
+                        <sup>superscript text</sup>
+                        <tg-spoiler>spoiler</tg-spoiler>
+                        
+                        <a href="#note-1">Reference</a>
+                        <a href="https://t.me/">inline URL</a>
+                        <a href="mailto:user@example.com">inline e-mail</a>
+                        <a href="tel:+123456789">inline phone number</a>
+                        <a href="tg://user?id=123456789">inline mention of a user</a>
+                        <a href="#chapter-1">in-document link</a>
+                        <a name="chapter-1"></a>
+                        
+                        <tg-reference name="note-1">Referenced text</tg-reference>
+                        <tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>
+                        <img src="tg://emoji?id=5368324170671202286" alt="👍"/>
+                        <tg-time unix="1647531900" format="wDT">22:45 tomorrow</tg-time>
+                        <tg-math>x^2 + y^2</tg-math>
+                        
+                        #hashtag ${'$'}USD +12345678901, card: 4242 4242 4242 4242, https://t.me t.me a@t.me /command @username
+                        
+                        all the text above was on the same line
+                        
+                        <h1>Heading 1</h1>
+                        <h2>Heading 2</h2>
+                        <h3>Heading 3</h3>
+                        <h4>Heading 4</h4>
+                        <h5>Heading 5</h5>
+                        <h6>Heading 6</h6>
+                        
+                        <a name="chapter-2"></a>
+                        
+                        <p>Paragraph text</p>
+                        <pre>pre-formatted fixed-width code block</pre>
+                        <pre><code class="language-python">  print('pre-formatted fixed-width code block written in the Python programming language')</code></pre>
+                        <footer>Footer text</footer>
+                        <hr/>
+                        <ul><li>unordered list item</li></ul>
+                        <ol><li>ordered list item</li></ol>
+                        <ol start="3" type="a" reversed><li>ordered list item</li></ol>
+                        <ol><li value="7" type="i">ordered list item with explicit number</li></ol>
+                        <ul>
+                        <li><input type="checkbox" checked>Checked checkbox</li>
+                        <li><input type="checkbox">Unchecked checkbox</li>
+                        </ul>
+                        
+                        <blockquote>Block quotation started<br>Block quotation continued<br>The last line of the block quotation<cite>The Author</cite></blockquote>
+                        <aside>Pull quote<cite>The Author</cite></aside>
+                        
+                        <img src="https://telegram.org/example/photo.jpg"/>
+                        <video src="https://telegram.org/example/video.mp4"></video>
+                        <audio src="https://telegram.org/example/audio.mp3"></audio>
+                        <audio src="https://telegram.org/example/audio.ogg"></audio>
+                        <video src="https://telegram.org/example/animation.gif"></video>
+                        
+                        <figure><img src="https://telegram.org/example/photo.jpg" tg-spoiler/><figcaption>Photo caption<cite>Photo credit</cite></figcaption></figure>
+                        <figure><video src="https://telegram.org/example/video.mp4" tg-spoiler></video><figcaption>Video caption</figcaption></figure>
+                        <figure><audio src="https://telegram.org/example/audio.mp3"></audio><figcaption>Audio caption</figcaption></figure>
+                        <figure><audio src="https://telegram.org/example/audio.ogg"></audio><figcaption>Voice note caption</figcaption></figure>
+                        <figure><video src="https://telegram.org/example/animation.gif" tg-spoiler></video><figcaption>Animation caption</figcaption></figure>
+                        
+                        <tg-map lat="41.9" long="12.5" zoom="14"/>
+                        <figure><tg-map lat="41.9" long="12.5" zoom="14"/><figcaption>Map caption</figcaption></figure>
+                        
+                        <tg-collage><img src="https://telegram.org/example/photo.jpg"/><video src="https://telegram.org/example/video.mp4"/></tg-collage>
+                        <tg-collage><video src="https://telegram.org/example/video.mp4"/><img src="https://telegram.org/example/photo.jpg"/><figcaption>Collage caption</figcaption></tg-collage>
+                        <tg-slideshow><img src="https://telegram.org/example/photo.jpg"/><video src="https://telegram.org/example/video.mp4"/></tg-slideshow>
+                        <tg-slideshow><video src="https://telegram.org/example/video.mp4"/><img src="https://telegram.org/example/photo.jpg"/><figcaption>Slideshow caption</figcaption></tg-slideshow>
+                        
+                        <table><tr><th>Header 1</th><th>Header 2</th></tr><tr><td>Value 1</td><td>Value 2</td></tr></table>
+                        <table bordered striped><caption>Table caption</caption>
+                        <tr><td colspan="2" rowspan="2" align="left">Value</td><td align="center">Value2</td><td align="right">Value3</td></tr>
+                        <tr><td valign="top">Value4</td><td valign="middle">Value5</td><td valign="bottom">Value6</td></tr>
+                        <tr><td>Value7</td></tr></table>
+                        
+                        <details><summary>Title</summary>Content</details>
+                        <details open><summary>Title</summary>Content</details>
+                        <tg-math-block>E = mc^2</tg-math-block>
+                    """.trimIndent()
+                )
+            )
+        }
+
+        // sendRichMessage with Markdown-formatted content
+        onCommand("rich_markdown") {
+            val sent = sendRichMessage(
+                it.chat.id,
+                InputRichMessageMarkdown(
+                    testMarkdownText
+                )
+            )
+            println(sent)
+        }
+
+        // sendRichMessage with Markdown-formatted content
+        onCommand("rich_markdown_medialess") {
+            val sent = sendRichMessage(
+                it.chat.id,
+                InputRichMessageMarkdown(
+                    testMarkdownMediaLessText
+                )
+            )
+            println(sent)
+        }
+
+        // sendRichMessage with Markdown-formatted content
+        onCommand("rich_markdown_blocks") {
+            val sent = sendRichMessage(
+                it.chat.id,
+                testMarkdownInputRichMessageBlocks
+            )
+            println(sent)
+        }
+
+        // sendRichMessage with Markdown-formatted content
+        onCommand("rich_markdown_medialess_blocks") {
+            val sent = sendRichMessage(
+                it.chat.id,
+                testMarkdownMediaLessInputRichMessageBlocks
+            )
+            println(sent)
+        }
+
+        // sendRichMessageDraft: stream partial rich messages sharing one draftId, then finalize
+        // with a full sendRichMessage. Emulates streaming of an AI-generated reply.
+        onCommand("rich_draft") {
+            val chatId = it.chat.id.toChatId()
+            val draftId = 1L
+            val parts = listOf(
+                "Thinking",
+                "Thinking about *rich* messages",
+                "Thinking about *rich* messages and how to _stream_ them"
+            )
+            parts.forEach { part ->
+                sendRichMessageDraft(chatId, draftId, InputRichMessageMarkdown(part))
+                delay(1000)
+            }
+            // finalize the streamed draft with the real message
+            sendRichMessage(chatId, InputRichMessageMarkdown("Done! Here is the *final* rich message."))
+        }
+
+        // EditChatMessageRichText: send a rich message, then edit it with new rich content
+        onCommand("rich_edit") {
+            val sent = sendRichMessage(it.chat.id, InputRichMessageMarkdown("*Original* rich message"))
+            delay(2000)
+            execute(
+                EditChatMessageRichText(
+                    chatId = sent.chat.id,
+                    messageId = sent.messageId,
+                    // the new rich_message parameter of editMessageText
+                    richMessage = InputRichMessageMarkdown("*Edited* rich message — now _updated_")
+                )
+            )
+        }
+
+        // === Bots API 10.2 additions: InputRichBlocks DSL + rich message media ===
+
+        // InputRichMessageBlocks { } — build a rich message from a typed InputRichBlock tree instead
+        // of an HTML/Markdown string (exactly one of html/markdown/blocks may be used). The lambda is an
+        // InputRichBlocksBuilder; buildInputRichBlocks { } returns the raw List<InputRichBlock> the same way.
+        onCommand("rich_blocks") {
+            sendRichMessage(
+                it.chat.id,
+                InputRichMessageBlocks {
+                    heading("Rich blocks (Bots API 10.2)", level = 1)
+                    paragraph {
+                        plain("This message is built from ")
+                        bold("structured InputRichBlocks")
+                        plain(" — no HTML or Markdown string is involved.")
+                    }
+
+                    h2("Lists")
+                    h3("Ordered")
+                    orderedList {
+                        item(0) { paragraph("A plain list item") }
+                        item(1) { paragraph { url("google", "google.com") } }
+                        item(2, hasCheckbox = true, isChecked = true) { paragraph("A plain list item") }
+                        item(3, hasCheckbox = true, isChecked = false) { paragraph("A plain list item") }
+                    }
+                    divider()
+                    h3("Unordered")
+                    unorderedList {
+                        item { paragraph("A plain list item") }
+                        item { paragraph { url("google", "google.com") } }
+                        item(hasCheckbox = true, isChecked = true) { paragraph("A plain list item") }
+                        item(hasCheckbox = true, isChecked = false) { paragraph("A plain list item") }
+                    }
+
+                    divider()
+
+                    heading("Code", level = 2)
+                    preformatted("val answer = 42", language = "kotlin")
+
+                    heading("Quotation", level = 2)
+                    blockQuotation {
+                        paragraph {
+                            plain("Quotations are themselves made of nested blocks — ")
+                            italic("including inline formatting")
+                            plain(".")
+                        }
+                    }
+                }
+            )
+        }
+
+        // sendRichMessageDraft with blocks: the thinking() block is only valid inside a draft and is used
+        // to stream a model's reasoning before the finalized rich message is sent via sendRichMessage.
+        onCommand("rich_blocks_draft") {
+            val chatId = it.chat.id.toChatId()
+            val draftId = 2L
+            listOf("Analyzing your request", "Composing a structured answer").forEach { step ->
+                sendRichMessageDraft(
+                    chatId,
+                    draftId,
+                    InputRichMessageBlocks { thinking(step) }
+                )
+                delay(1000)
+            }
+            // finalize the streamed draft with the real (non-thinking) blocks
+            sendRichMessage(
+                chatId,
+                InputRichMessageBlocks {
+                    heading("Answer", level = 2)
+                    paragraph("Here is the finalized, structured reply.")
+                }
+            )
+        }
+
+        // Rich message media: send me a photo and it gets embedded into a rich message two ways.
+        onPhoto { message ->
+            // reuse the received file by its fileId (no upload). To upload a brand-new file instead,
+            // build the TelegramMedia from file.asMultipartFile() — SendRichMessage collects any
+            // MultipartFile inside the rich message and uploads it as attach://<id> automatically.
+            val photoMedia = TelegramMediaPhoto(message.content.media.fileId)
+
+            // (1) referenced from HTML via tg://photo?id=<id>, resolved through InputRichMessage.media
+            sendRichMessage(
+                message.chat.id,
+                InputRichMessageHTML(
+                    """
+                        <h2>Your photo, referenced from HTML</h2>
+                        <p>Below is your photo, referenced via <code>tg://photo?id=userphoto</code>:</p>
+                        <img src="tg://photo?id=userphoto"/>
+                    """.trimIndent(),
+                    media = listOf(
+                        InputRichMessageMedia(id = "userphoto", media = photoMedia)
+                    )
+                )
+            )
+
+            // (2) as a first-class media block inside an InputRichBlocks tree
+            sendRichMessage(
+                message.chat.id,
+                InputRichMessageBlocks {
+                    heading("Your photo, as a media block", level = 2)
+                    paragraph("The same photo, this time a photo() block inside the blocks tree:")
+                    photo(photoMedia)
+                }
+            )
+        }
+
+        // waitRichMessage expectation: wait for the user to send a rich message
+        onCommand("wait_rich") {
+            reply(it, "Send me a rich message now")
+            val richMessageContent = waitRichMessage().first()
+            reply(
+                it,
+                "Got rich message with ${richMessageContent.richMessage.blocks.size} block(s)"
+            )
+        }
+
+        onGuestRequestMessage {
+            val withTextContent = it.withContentOrNull<TextContent>() ?: return@onGuestRequestMessage
+            val haveCommand = withTextContent.content.text.contains("/rich_guest")
+            if (haveCommand) {
+                answer(
+                    it.guestQueryId,
+                    InlineQueryResultArticle(
+                        InlineQueryId("rich_content"),
+                        "Send rich message",
+                        InputRichMessageContent(
+                            InputRichMessageMarkdown(
+                                testMarkdownText
+                            )
+                        )
+                    )
+                )
+            }
+        }
+
+        // onRichMessage trigger: incoming messages carrying the new rich_message field
+        onRichMessage { message ->
+            val richMessage = message.content.richMessage
+            println("=== Rich message received ===")
+            println("  isRtl:  ${richMessage.isRtl}")
+            println("  blocks: ${richMessage.blocks.size}")
+            richMessage.blocks.forEachIndexed { index, block ->
+                println("  [$index] $block")
+            }
+            reply(message, "Received a rich message with ${richMessage.blocks.size} block(s)")
+            execute(
+                message.content.createResend(
+                    message.chat.id,
+                )
+            )
+        }
+
+        // InputRichMessageContent as InputMessageContent of inline query results
+        onBaseInlineQuery { query ->
+            answer(
+                query,
+                results = listOf(
+                    InlineQueryResultArticle(
+                        InlineQueryId("rich_html"),
+                        "Rich message (HTML)",
+                        // InputRichMessageContent wraps an InputRichMessage and is a valid InputMessageContent
+                        InputRichMessageContent(
+                            InputRichMessageHTML("<b>Bold</b> rich message sent via inline query")
+                        ),
+                        description = "InputRichMessageContent built from HTML"
+                    ),
+                    InlineQueryResultArticle(
+                        InlineQueryId("rich_markdown"),
+                        "Rich message (Markdown)",
+                        InputRichMessageContent(
+                            InputRichMessageMarkdown("*Bold* rich message sent via inline query")
+                        ),
+                        description = "InputRichMessageContent built from Markdown"
+                    )
+                ),
+                cachedTime = 0
+            )
+        }
+
+        // onlyRichMessageContentMessages: filter a Flow<ContentMessage<*>> down to rich message content
+        allUpdatesFlow
+            .mapNotNull { it.baseSentMessageUpdateOrNull() ?.data ?.contentMessageOrNull() }
+            .onlyRichMessageContentMessages()
+            .subscribeLoggingDropExceptions(scope = this) { richMessageContentMessage ->
+                println("[onlyRichMessageContentMessages] ${richMessageContentMessage.content.richMessage.blocks.size} blocks")
+            }
+
+        setMyCommands(
+            BotCommand("rich_html", "Send a rich message described with HTML"),
+            BotCommand("rich_markdown", "Send a rich message described with Markdown"),
+            BotCommand("rich_blocks", "Send a rich message built from the InputRichBlocks DSL"),
+            BotCommand("rich_draft", "Stream a rich message draft, then finalize it"),
+            BotCommand("rich_blocks_draft", "Stream a blocks draft with thinking(), then finalize it"),
+            BotCommand("rich_edit", "Send a rich message and edit it with new rich content"),
+            BotCommand("wait_rich", "Wait for you to send a rich message"),
+        )
+
+        allUpdatesFlow.subscribeLoggingDropExceptions(scope = this) {
+            println(it)
+        }
+    }.second.join()
+}

RightsChangerBot/README.md

@@ -1,12 +1,54 @@
-# RightsChanger
+# RightsChangerBot
 
-All the commands should be called with reply to some common user.
+A long-polling/FSM example for changing a member's chat permissions and a channel administrator's rights with inline keyboards. The bot registers its commands in the all-group-chats scope and prints every received update to standard output.
 
-* Use `/simple` with bot to get request buttons for non-independent permissions change
-* Use `/granular` with bot to get request buttons for independent permissions change
+## Commands and callbacks
+
+### Member permissions
+
+Run these commands in a group or supergroup as a reply to a non-administrator's message:
+
+- `/simple` shows toggles for polls, other messages, and web-page previews. Changes use Telegram's dependent/common permission model (`useIndependentChatPermissions = false`), so related permissions may change together.
+- `/granular` shows independent toggles for text messages, other messages, audio, voice notes, video, video notes, photos, web-page previews, polls, and documents (`useIndependentChatPermissions = true`).
+
+The keyboard shows `✅` for allowed, `❌` for denied, and no suffix when Telegram reports no explicit value. Clicking a button restricts the replied-to member and edits the keyboard with the refreshed state. If the command is not a valid reply, or the target is an administrator/owner rather than a normal or restricted member, the bot usually returns without a response.
+
+### Channel administrator rights
+
+Send `/rights_in_channel` in a private chat with the bot. Telegram's chat/user request buttons used by this flow are available only in private chats, even though the command is registered only in the group command-menu scope.
+
+1. Select a channel where the bot is already a member. The picker requests `can_promote_members` and `can_restrict_members` for both the bot and the selecting user.
+2. Select a user, or send `/cancel` during either selection step.
+3. If the selected user is currently a channel administrator, the bot sends a keyboard for refreshing or toggling post-message, edit-message, delete-message, post-story, edit-story, and delete-story rights.
+
+Selecting a non-administrator ends the flow without a message. A stale keyboard whose target is later demoted can display **Promote to admin**; that action promotes the target with the post-messages right enabled. Telegram allows the bot to change an administrator's rights only when the bot promoted that administrator itself.
+
+Callbacks are processed only when clicked by the configured allowed user. They are not explicitly answered with `answerCallbackQuery`, so Telegram clients may retain their loading indicator until the edit completes or the callback times out.
+
+## Setup, permissions, and security
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- Choose one trusted Telegram numeric user ID as `ALLOWED_USER_ID`. `/simple` and all permission-changing callbacks are restricted to this ID.
+- Promote the bot in managed groups/channels. It needs `can_restrict_members` for member permissions and `can_promote_members` for channel administrator rights, plus enough rights to read member state and send/edit its keyboard messages. It cannot grant rights it does not possess.
+- BotFather privacy mode can remain enabled because the group workflows use commands, replies, and callbacks.
+- Treat console output as sensitive: the example prints every raw update, and handler failures print stack traces.
+
+Current authorization caveats: `/rights_in_channel` has no sender filter, although its resulting mutation callbacks still require `ALLOWED_USER_ID`. `/granular` checks `ALLOWED_USER_ID` in normal public chats but accepts channel-post commands without that sender check; its callbacks remain protected. Keep the bot limited to trusted chats.
+
+Long polling automatically removes an existing webhook at startup. Run only one update consumer for the token at a time.
+
+## Arguments
+
+The bot requires the token first and the allowed numeric user ID second. Debug logging is enabled only when the third argument is exactly `debug`.
 
 ## Launch
 
+From the repository root:
+
 ```bash
-../gradlew run --args="BOT_TOKEN allowed_user_id_long"
+./gradlew :RightsChangerBot:run --args="<BOT_TOKEN> <ALLOWED_USER_ID>"
+```
+
+```bash
+./gradlew :RightsChangerBot:run --args="<BOT_TOKEN> <ALLOWED_USER_ID> debug"
 ```

RightsChangerBot/src/main/kotlin/RightsChanger.kt

@@ -40,14 +40,20 @@ import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.mapNotNull
 
+/** States used by the private-chat flow that selects a channel and one of its users. */
 sealed interface UserRetrievingStep : State {
+    /** Waits for the user to share a channel in the private chat identified by [context]. */
     data class RetrievingChannelChatState(
         override val context: ChatId
     ) : UserRetrievingStep
+
+    /** Waits for a user selection after [channelId] has been shared. */
     data class RetrievingUserIdChatState(
         override val context: ChatId,
         val channelId: ChatId
     ) : UserRetrievingStep
+
+    /** Carries the selected [channelId] and [userId] to the administrator-rights keyboard step. */
     data class RetrievingChatInfoDoneState(
         override val context: ChatId,
         val channelId: ChatId,
@@ -55,6 +61,12 @@ sealed interface UserRetrievingStep : State {
     ) : UserRetrievingStep
 }
 
+/**
+ * Runs the RightsChangerBot FSM and callback handlers using long polling.
+ *
+ * @param args the bot token, the only user ID authorized to mutate rights, and optionally `debug` as the third
+ * element to enable formatted KSLog output
+ */
 @OptIn(PreviewFeature::class)
 suspend fun main(args: Array<String>) {
     val botToken = args.first()

SlotMachineDetectorBot/README.md

@@ -1,9 +1,39 @@
 # SlotMachineDetectorBot
 
-This bot must reply with information about slot machine answer
+A long-polling example that distinguishes slot-machine dice from other Telegram
+dice animations and decodes the slot reels.
 
-## Launch
+## Trigger and output
+
+The bot handles every dice message and defines no commands.
+
+- For a slot-machine dice, it calls `calculateSlotMachineResult` and replies in the
+  exact format `<left-reel>|<center-reel>|<right-reel>`.
+- If a slot-machine value cannot be decoded, the handler sends no reply.
+- For every other dice animation, it replies
+  `There is no slot machine dice in message`.
+
+The example reports the three decoded reels only. It does not calculate a numeric
+score or decide whether the combination wins.
+
+## Setup, permissions, and privacy
+
+1. Create a bot, obtain its token, and keep the token private.
+2. Start a private chat with it, or add it to a group where dice should be observed.
+3. Allow the bot to send replies in that chat.
+
+Dice are ordinary non-command messages. In groups, configure Telegram's bot privacy
+setting so the desired dice updates are delivered; disable privacy mode if the bot
+should inspect all group dice. No administrator-only API methods are used. The bot
+stores no message or dice data.
+
+## Run
+
+From the repository root:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :SlotMachineDetectorBot:run --args="BOT_TOKEN"
 ```
+
+The first argument is the required bot token. Omitting it causes startup to fail;
+additional arguments are ignored. This launcher has no debug or test-server flag.

SlotMachineDetectorBot/src/main/kotlin/SlotMachineDetectorBot.kt

@@ -6,6 +6,13 @@ import dev.inmo.tgbotapi.extensions.utils.*
 import dev.inmo.tgbotapi.types.dice.SlotMachineDiceAnimationType
 import kotlinx.coroutines.*
 
+/**
+ * Starts the long-polling slot-machine detector.
+ *
+ * [args] must contain the bot token first; later elements are ignored. Slot-machine
+ * dice receive a pipe-separated three-reel reply, while other dice receive an
+ * explanatory reply. An undecodable slot-machine result is silently ignored.
+ */
 suspend fun main(args: Array<String>) {
     val bot = telegramBot(args.first())
 

StarTransactionsBot/README.md

@@ -1,9 +1,65 @@
 # StarTransactionsBot
 
-This bot basically have no any useful behaviour, but you may customize it as a playground
+A long-polling Telegram Stars playground for invoices, transaction history, paid
+media, pre-checkout approval, and refund updates.
 
-## Launch
+## Commands
+
+- `/start` replies with a sample invoice charging `1` Star, payload
+  `sample payload`, and a **Pay** button. Matching pre-checkout queries are approved
+  automatically.
+- `/transactions` works only in the chat whose numeric ID was supplied as the
+  second program argument. It replies with the bot's first transaction page.
+
+The commands are not registered in Telegram's command menu.
+
+## Transaction pages
+
+Pages use an offset and a default limit of `10`. Each returned transaction includes
+its ID, date, amount, direction (`incoming`, `outgoing`, or `unknown`), and partner
+type. The inline keyboard contains:
+
+- `<` when a previous nonnegative offset exists;
+- `>` on every page, using `offset + limit`, even when no later records exist.
+
+Selecting either button fetches that page and edits the existing text message. The
+initial `/transactions` command is admin-chat filtered; pagination callbacks are not
+independently filtered, so keep the resulting message in the private admin chat.
+Pagination state is encoded in callback data and is not persisted by the bot.
+
+## Other triggers
+
+- A photo or video is sent back as paid media costing `1` Star.
+- A visual gallery is downloaded to temporary files and re-uploaded as one-Star
+  paid media, retaining its caption above the media; only photos and videos are used.
+- Paid-media-info messages are printed to standard output.
+- Refunded-payment events receive a reply containing the payment information.
+- Every received update is printed to standard output.
+
+## Setup, permissions, and payment safety
+
+Create a bot, keep its token private, and choose the numeric ID of the user who may
+open transaction history. Use that user's private chat, and allow the bot to send
+messages, invoices, photos, and videos. The Telegram environment and client must
+support Stars and paid media; purchasers need Stars to complete payments.
+
+This is a charging example: `/start` and delivered photo/video content can create
+one-Star purchase flows. Use test accounts or Telegram's test environment when
+appropriate. The code approves its sample pre-checkout query but performs no
+fulfilment after payment. No chat-administrator methods or webhook are configured.
+
+## Run
+
+From the repository root, pass the token and decimal admin ID first:
 
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :StarTransactionsBot:run --args="BOT_TOKEN ADMIN_USER_ID"
+```
+
+Both arguments are required; an absent or nonnumeric admin ID stops startup. The
+optional, case-sensitive flags `debug` and `testServer` may follow them in either
+order to enable formatted logging or Telegram's test API.
+
+```bash
+./gradlew :StarTransactionsBot:run --args="BOT_TOKEN ADMIN_USER_ID debug testServer"
 ```

StarTransactionsBot/src/main/kotlin/StarTransactionsBot.kt

@@ -37,7 +37,13 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * An example bot that interacts with Telegram Stars API (used for payments)
+ * Starts the long-polling Telegram Stars and paid-media playground.
+ *
+ * The first element of [args] must be the bot token and the second a numeric admin
+ * user/chat ID authorized for `/transactions`. Optional exact values `debug` and
+ * `testServer` enable diagnostic logging and Telegram's test environment. Other
+ * handlers create a one-Star invoice or paid media and report payment-related
+ * updates.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

StickerInfoBot/README.md

@@ -0,0 +1,47 @@
+# StickerInfoBot
+
+A multiplatform long-polling example that looks up Telegram sticker-set metadata. `StickerInfoBotLib` contains the shared JVM/JS behavior, with a browser entry point in `jsMain`; `jvm_launcher` provides the command-line entry point. The bot has no commands.
+
+## Behavior and output
+
+At startup, the bot calls `getMe` and reports the returned bot information through the active launcher. It then handles:
+
+- **Sticker messages:** looks up the sticker's set and replies to the message with the set name, title, and type (`Regular`, `Mask`, `Custom emoji`, or the raw unknown type). If no set can be resolved, it replies with **Looks like this stickerset has been removed**.
+- **Text messages:** shows a typing action, scans the message entities for custom emoji, resolves their stickers and sticker sets, removes duplicate sets, and replies with the same metadata for each set. Sets without a resolvable name are skipped. Text without resolvable custom emoji produces no reply.
+
+Long output from text containing several custom-emoji sets is split into Telegram-sized messages. Every received update is printed to the JVM terminal or browser developer console, and uncaught processing errors print stack traces.
+
+## Telegram setup and permissions
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- No administrator rights are required in a private chat. The bot only needs to receive the source message and be allowed to send replies.
+- To inspect arbitrary sticker and custom-emoji messages in a group, either disable privacy mode with BotFather's `/setprivacy` or promote the bot to administrator. With privacy mode enabled as a regular member, Telegram does not deliver most ordinary group messages to it.
+- The example uses long polling and automatically removes an existing webhook at startup. Run only one launcher for a token at a time.
+
+## Launchers
+
+Run these commands from the repository root.
+
+### JVM
+
+The required first argument is the bot token. Additional arguments are ignored.
+
+```bash
+./gradlew :StickerInfoBot:jvm_launcher:run --args="<BOT_TOKEN>"
+```
+
+> **Known issue:** `jvm_launcher/build.gradle` declares `StickerInfoBotJvmKt`, while the current launcher filename produces `StickerInfoBotBotJvmKt`. The `run` task cannot start until that main-class setting is corrected; it is left unchanged by this documentation-only update.
+
+The JVM launcher prints the startup `getMe` result, raw updates, and errors to standard output.
+
+### Browser/JS
+
+Start the Kotlin/JS browser development run:
+
+```bash
+./gradlew :StickerInfoBot:StickerInfoBotLib:jsBrowserDevelopmentRun
+```
+
+Enter the token in the bundled form and press **Start bot**. The page renders the startup `getMe` result; raw updates and errors appear in the browser developer console. The bot runs only while the page remains active, and every form submission starts another polling instance.
+
+The browser handles the bot token in client-side code. Use this target only from a trusted local page and do not expose a token through a publicly hosted copy.

StickerInfoBot/StickerInfoBotLib/src/commonMain/kotlin/StickerInfoBot.kt

@@ -21,6 +21,11 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.currentCoroutineContext
 
+/**
+ * Formats this sticker set's name, title, and type as Telegram text entities.
+ *
+ * A `null` receiver produces a bold warning that the sticker set appears to have been removed.
+ */
 fun StickerSet?.buildInfo() = buildEntities {
     if (this@buildInfo == null) {
         bold("Looks like this stickerset has been removed")
@@ -38,6 +43,15 @@ fun StickerSet?.buildInfo() = buildEntities {
     }
 }
 
+/**
+ * Creates and runs the shared StickerInfoBot behavior using long polling.
+ *
+ * Sticker messages are answered with their set metadata. Text messages are scanned for custom-emoji entities and
+ * answered with metadata for each distinct resolved sticker set. Every update is also logged.
+ *
+ * @param token the Telegram bot token
+ * @param print receives the bot information returned by the startup `getMe` request
+ */
 suspend fun activateStickerInfoBot(
     token: String,
     print: (Any) -> Unit

StickerInfoBot/StickerInfoBotLib/src/jsMain/kotlin/StickerInfoBot.kt

@@ -4,6 +4,11 @@ import org.w3c.dom.*
 
 private val scope = CoroutineScope(Dispatchers.Default)
 
+/**
+ * Installs the browser token form after `DOMContentLoaded` and starts a bot for every submission.
+ *
+ * Each bot receives its token from `bot_token`; its startup information is appended under `bots_container`.
+ */
 fun main() {
     document.addEventListener(
         "DOMContentLoaded",

StickerInfoBot/jvm_launcher/src/main/kotlin/StickerInfoBotBotJvm.kt

@@ -1,3 +1,8 @@
+/**
+ * Runs [activateStickerInfoBot] on the JVM and prints its startup bot information to standard output.
+ *
+ * @param args the Telegram bot token as the first element; additional elements are ignored
+ */
 suspend fun main(args: Array<String>) {
     activateStickerInfoBot(args.first()) {
         println(it)

StickerSetHandler/README.md

@@ -1,9 +1,67 @@
 # StickerSetHandler
 
-Send sticker to this bot to form your own stickers set. Send /delete to delete this sticker set
+StickerSetHandler is a Kotlin/JVM long-polling example that creates and manages one Telegram sticker set for each
+private chat. It copies stickers sent to the bot into a set owned by the user.
 
-## How to run
+## Behavior
+
+| Trigger | Action |
+| --- | --- |
+| `/start` | Replies with a short hint for the `/delete` command. |
+| `/delete` | Deletes the chat's entire sticker set and replies `Deleted`; if deletion fails, it replies that it could not delete the set. |
+| A regular, mask, or custom-emoji sticker | Downloads and re-uploads the sticker. The first supported sticker creates the set; later compatible stickers are added to it. The bot replies with the created or newly added sticker. |
+| Any other update | Performs no chat action. Every update is still printed to standard output. |
+
+The deterministic set name is `s<chat_id>_by_<bot_username>`, and a newly created set is titled
+`Sticker set by <bot_first_name>`. The original sticker format, emoji (or a smiling fallback), mask position, and the
+initial custom-emoji repainting setting are preserved where applicable. Sticker keywords are not copied. Sticker
+types cannot be mixed in one set: the first sticker determines whether the set is regular, mask, or custom emoji.
+
+After `/delete`, sending another supported sticker recreates the set. Sticker objects that the library does not
+recognize are ignored.
+
+## Telegram setup and permissions
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Open a private chat with the bot and start it.
+3. Send a sticker, or use `/start` to display the available command.
+
+No Telegram administrator rights or special BotFather modes are required for this private-chat workflow. The
+process needs network access and a writable temporary directory because it downloads each sticker before uploading
+it to Telegram.
+
+Use the example in private chats only. The code passes the incoming chat ID as the sticker-set owner's user ID;
+private-chat IDs identify the user, while group and channel IDs do not. Telegram also enforces its own account,
+sticker-type, format, and sticker-set limits, so an otherwise supported request can still be rejected.
+
+## Arguments
+
+| Position | Argument | Required | Description |
+| --- | --- | --- | --- |
+| 1 | `BOT_TOKEN` | Yes | Bot API token issued by BotFather. |
+
+The program reads only the first argument. It does not implement `debug`, `testServer`, or other optional flags, and
+it exits during startup if the token is omitted.
+
+## Run
+
+From the repository root:
 
 ```bash
-./gradlew run --args="TOKEN"
+./gradlew :StickerSetHandler:run --args="<BOT_TOKEN>"
 ```
+
+Keep the real token out of source control and be aware that command-line arguments may be visible in shell history
+or process listings. The bot polls until the process is stopped.
+
+## Safety notes
+
+- `/delete` has no confirmation step and removes the complete set, not just its most recent sticker.
+- The set name contains the numeric private-chat/user ID. That identifier can be exposed when the sticker-set name
+  or link is displayed or shared.
+- There is no allowlist, rate limit, or moderation. Every supported sticker is downloaded to temporary storage and
+  uploaded again, so expose the bot only with suitable API, bandwidth, and disk limits.
+- Every received update is written to standard output, and several failure paths print stack traces. Those logs can
+  contain user, chat, message, and file metadata and should be protected accordingly.
+- Any sticker-set lookup failure is treated as if the set were absent, so a temporary Telegram or network failure
+  can lead to a failed creation attempt rather than a retry.

StickerSetHandler/src/main/kotlin/StickerSetHandlerBot.kt

@@ -24,7 +24,13 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
 /**
- * Send sticker to this bot to form your own stickers set. Send /delete to delete this sticker set
+ * Starts the long-polling sticker-set example using the bot token in the first command-line argument.
+ *
+ * Supported sticker messages create or extend the deterministic set for the current private chat, while `/delete`
+ * removes that set. Private chats are required because the chat ID is also passed to Telegram as the set owner's
+ * user ID.
+ *
+ * @param args command-line arguments whose first element must be a Bot API token
  */
 suspend fun main(args: Array<String>) {
     telegramBotWithBehaviourAndLongPolling(

SuggestedPosts/README.md

@@ -1,9 +1,59 @@
-# StickerSetHandler
+# SuggestedPosts
 
-Send sticker to this bot to form your own stickers set. Send /delete to delete this sticker set
+A long-polling playground for channel direct messages and suggested-post lifecycle
+updates.
 
-## How to run
+## Commands and content triggers
+
+- `/start` fetches and prints full information for the command's chat. It sends no
+  reply and is not registered in Telegram's command menu.
+- Every delivered channel-direct-message content message is printed with its chat
+  information, then resent to the same direct-message chat with empty
+  `SuggestedPostParameters` so it becomes a suggested post.
+- Channel paid-post content is printed to standard output.
+
+## Suggested-post lifecycle
+
+For each detected suggested post, the bot races three branches:
+
+1. wait for a suggested-post-approved event from the same chat;
+2. wait for a suggested-post-declined event from the same chat;
+3. after one-second delays, send `3`, `2`, and `1`, then decline the post.
+
+A matching approval or decline ends the countdown branch. The waits correlate by
+chat ID rather than individual suggested-post message ID, which matters when several
+suggestions are active in the same chat. The bot does not approve posts itself and
+does not set a price or scheduled publication time.
+
+Lifecycle events are printed and receive these replies:
+
+- paid → `Paid`;
+- approved → `Approved`;
+- declined → `Declined`;
+- refunded → `Refunded`;
+- approval failed → `Approval failed`.
+
+Every update is also printed. State exists only in active coroutine waits; restarting
+the bot cancels pending countdowns and forgets active suggestions.
+
+## Setup and permissions
+
+Use a channel with direct messages and suggested posts enabled. Add the bot with
+enough channel access to receive direct-message updates, resend their content, send
+countdown/reply messages, and decline suggested posts. The code does not validate
+these permissions at startup and configures no webhook.
+
+Full updates, chat details, suggested content, and payment-related events are logged.
+Use a private test channel and protect process output.
+
+## Run
+
+From the repository root:
 
 ```bash
-./gradlew run --args="TOKEN"
+./gradlew :SuggestedPosts:run --args="BOT_TOKEN"
 ```
+
+The token is the required first argument. Optional exact flags may follow it in any
+order: `debug` enables formatted logging, and `testServer` selects Telegram's test
+environment. Other arguments are ignored.

SuggestedPosts/src/main/kotlin/SuggestedPostsBot.kt

@@ -41,7 +41,12 @@ import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 
 /**
- * This place can be the playground for your code.
+ * Starts the long-polling suggested-post lifecycle playground.
+ *
+ * The first element of [args] must be the bot token. Optional exact values `debug`
+ * and `testServer` enable diagnostic logging and Telegram's test environment.
+ * Channel direct-message content is resent as a suggestion, then automatically
+ * declined after a three-message countdown unless an approval or decline arrives.
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()

TagsBot/README.md

@@ -0,0 +1,57 @@
+# TagsBot
+
+A long-polling example for setting chat-member tags, delegating tag-management
+rights, and reading sender tags from group messages.
+
+## Commands
+
+All commands target the identifiable user who sent the replied-to group content
+message. Without such a reply, they silently do nothing.
+
+- `/setChatMemberTag <tag>` calls `setChatMemberTag` for that user. The tag is the
+  command's remaining text after removing at most one leading space; it is not
+  otherwise trimmed.
+- `/removeChatMemberTag` clears that user's tag by sending `null`.
+- `/setCanManageTags true` invokes `promoteChatAdministrator` with
+  `canManageTags = true`. Any remaining text other than exact, lowercase `true`
+  sets that permission to `false`.
+
+The bot sends no success reply for these operations and does not register commands
+in Telegram's command menu.
+
+## Message trigger and storage
+
+For every delivered group content message that can be interpreted as potentially
+coming from a user, the bot sends two replies:
+
+- `Tag after casting: <tag>` using the typed `senderTag` property;
+- `Tag by getting via risk API: <tag>` using the raw `sender_tag` field.
+
+The displayed value may be `null`. Command messages also reach this content handler.
+Tags and tag-management rights are stored by Telegram as chat-member state; this
+example has no local map, database, or persistence layer. It prints its own bot
+information at startup and logs every received update.
+
+## Setup, permissions, and privacy
+
+1. Create a bot, obtain its token, and keep it private.
+2. Add it to a test group and allow it to send messages.
+3. Grant the Telegram administrator rights needed to set member tags and promote
+   members/change their `canManageTags` permission.
+
+To inspect ordinary group messages, configure bot privacy so Telegram delivers them;
+an administrator bot normally has broader visibility, but verify delivery in the
+target group. The bot publicly echoes sender tags and logs full updates, so protect
+the group and process output. The code configures no webhook.
+
+## Run
+
+From the repository root:
+
+```bash
+./gradlew :TagsBot:run --args="BOT_TOKEN"
+```
+
+The first argument is the required token. Optional exact flags may follow it in any
+order: `debug` enables formatted logging, and `testServer` selects Telegram's test
+environment. Other arguments are ignored.

TagsBot/src/main/kotlin/TagsBot.kt

@@ -39,6 +39,14 @@ import dev.inmo.tgbotapi.utils.buildEntities
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
+/**
+ * Starts the long-polling chat-member-tag example.
+ *
+ * The first element of [args] must be the bot token. Optional exact values `debug`
+ * and `testServer` enable diagnostic logging and Telegram's test environment.
+ * Reply-based commands set or clear a group member's tag and tag-management right;
+ * delivered group content receives replies showing its typed and raw sender tag.
+ */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
 

TopicsHandling/README.md

@@ -1,9 +1,47 @@
-# HelloBot
+# TopicsHandling
 
-The main purpose of this bot is just to answer "Oh, hi, " and add user mention here
+A long-polling example for Telegram forum-topic and private-chat-topic APIs. It executes topic-management commands, reports selected topic service events, and prints raw updates.
+
+## Commands and actions
+
+The commands take no arguments:
+
+- `/start_test_topics` runs a timed topic-management sequence. It creates a green **Test** topic, renames it to **Test 01**, and deletes it. In a forum supergroup it also closes/reopens the test topic; hides/unhides and closes/reopens the General topic; renames the General topic to a random 10-character value; and finally renames it to **Main topic**. Status replies are sent after each successful action.
+- `/delete_topic` deletes the forum topic containing the command. Outside a forum topic it returns silently, and it asks for no confirmation.
+- `/unpin_all_forum_topic_messages` unpins every pinned message in the topic containing the command. Outside a forum topic it returns silently and sends no success reply. Its registered command-menu description currently repeats the delete-topic description.
+
+In a private chat, `/start_test_topics` first checks the bot's `has_topics_enabled` flag. If private topics are disabled, it logs a warning and returns without replying. If enabled, it performs only the create, rename, and delete steps because private topics cannot be closed/reopened and have no General-topic sequence. The commands are registered only in the all-group-chats menu scope, so the private-chat command must be typed manually.
+
+## Event triggers
+
+The bot replies to these service events:
+
+- forum topic created or edited;
+- private topic created or edited;
+- forum topic reopened;
+- General topic hidden or unhidden.
+
+There is no topic-closed or topic-deleted reply handler. General-topic edits and reopens can match the generic edited/reopened handlers above, while hiding and unhiding use their dedicated handlers. All incoming updates are nevertheless logged. The source currently subscribes to the raw update flow twice, so each update is normally printed twice.
+
+## Setup, permissions, and safety
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- For group use, add it to a forum-enabled supergroup and promote it to administrator with `can_manage_topics`. It also needs permission to send messages; `/unpin_all_forum_topic_messages` additionally requires `can_pin_messages`.
+- Enable private-chat topics for the bot if the private variant of `/start_test_topics` should work.
+- BotFather privacy mode may remain enabled because the group interactions are commands and topic service events, and the bot must already be an administrator.
+
+There is no sender allowlist or administrator check in the command handlers. Any user whose command reaches the bot can make it delete a topic, remove topic pins, or run the General-topic mutation sequence using the bot's administrator rights. Use a disposable/trusted test chat or add authorization before deployment. The test sequence does not restore the General topic's previous name; it leaves it open and named **Main topic**.
+
+At startup the bot flushes accumulated updates before registering its handlers, so pending updates are discarded. Long polling also removes an existing webhook. Handler failures print stack traces.
+
+## Arguments
+
+The first argument is the required bot token. Additional arguments are ignored; there is no debug option.
 
 ## Launch
 
+From the repository root:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :TopicsHandling:run --args="<BOT_TOKEN>"
 ```

TopicsHandling/src/main/kotlin/TopicsHandling.kt

@@ -33,6 +33,14 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.delay
 
+/**
+ * Runs the TopicsHandling long-polling example.
+ *
+ * The bot exposes destructive forum-topic test commands, reports selected topic service events, and flushes pending
+ * updates at startup before subscribing to new ones.
+ *
+ * @param args the Telegram bot token as the first element; additional elements are ignored
+ */
 suspend fun main(vararg args: String) {
     telegramBotWithBehaviourAndLongPolling(
         args.first(),

UserChatShared/README.md

@@ -1,9 +1,68 @@
 # UserChatShared
 
-Use `/start` with bot to get request buttons. Bot will ask you to choose user/chat from your list and send it to him.
+A long-polling example of Telegram reply-keyboard buttons that request users, bots, groups, forums, or channels. It
+also shows how the resulting `users_shared` and `chat_shared` service messages can be handled.
+
+## Behavior
+
+1. Open a private chat with the bot and send `/start` (the command takes no arguments).
+2. The bot sends a persistent, resized reply keyboard. Pressing a request button opens Telegram's native peer
+   picker with that button's filters.
+3. After you confirm a selection, Telegram sends a `users_shared` or `chat_shared` service message containing the
+   request ID and selected peer data. These buttons do not produce callback queries or callback data.
+4. The bot uses the request ID to describe the selection, calls `getChat` as a best-effort lookup, and replies with
+   the identifier and lookup result. A failed lookup is shown as `null` rather than stopping the bot.
+
+The user/bot part of the keyboard provides:
+
+- one user or bot;
+- one non-Premium user, any user, one Premium user, or one bot;
+- multiple users or bots; and
+- multiple non-Premium users, any users, Premium users, or bots, up to the library's current
+  `keyboardButtonRequestUserLimit` maximum.
+
+Every user/bot button asks Telegram to include the selected peer's name, username, and photo. The handler replies
+once per selected ID. Its descriptive labels cover the single-selection request IDs; selections from the
+multiple-selection buttons use the fallback label `somebody O.o`.
+
+The chat part provides an unfiltered chat request plus these filtered requests:
+
+| Kind | Available filters |
+| --- | --- |
+| Channel | any, public, private, or owned by the selecting user |
+| Group | any, public, private, or owned by the selecting user |
+| Forum group | any, public, private, or owned by the selecting user |
+
+Here, public/private means with/without a public username. Every chat button asks Telegram to include the title,
+username, and photo. This example uses only the ID from the shared event for its `getChat` lookup and response; it
+does not print the requested snapshot fields directly.
+
+## Telegram setup and permissions
+
+- Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+- Send `/start` in a private chat. The command handler intentionally ignores `/start` in groups and channels, and
+  Telegram exposes user/chat request buttons only in private chats.
+- The buttons do not require the bot to be a member or administrator of a selected chat, and they request no user
+  or bot administrator rights. Consequently, sharing a peer does not guarantee that `getChat` can access it. Add
+  the bot to a selected group or channel when you want that lookup to succeed reliably.
+- The example uses long polling. Do not run another polling or webhook consumer with the same bot token at the same
+  time.
+
+## Arguments
+
+The first application argument is the required bot token. If the optional second argument is exactly `debug`, the
+example formats and prints the library's default KSLog output to standard output. Other extra arguments are ignored.
 
 ## Launch
 
+From the repository root:
+
 ```bash
-../gradlew run --args="BOT_TOKEN"
+./gradlew :UserChatShared:run --args="<BOT_TOKEN>"
+```
+
+To enable debug logging:
+
+```bash
+./gradlew :UserChatShared:run --args="<BOT_TOKEN> debug"
 ```