mirror of
https://github.com/InsanusMokrassar/TelegramBotAPI-examples.git
synced 2026-08-29 12:26:25 +00:00
update readmes
This commit is contained in:
97
RichMessagesBot/README.md
Normal file
97
RichMessagesBot/README.md
Normal file
@@ -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"
|
||||
```
|
||||
@@ -52,31 +52,23 @@ import kotlinx.coroutines.flow.first
|
||||
import kotlinx.coroutines.flow.mapNotNull
|
||||
|
||||
/**
|
||||
* This bot demonstrates Rich Messages support introduced in Telegram Bot API 10.1.
|
||||
* Runs a long-polling showcase of the rich-message APIs introduced in Telegram Bot API 10.1 and 10.2.
|
||||
*
|
||||
* Rich messages allow bots to send highly structured text (and to stream AI-generated replies
|
||||
* with seamless rich formatting). Telegram parses the provided HTML/Markdown into a structured
|
||||
* [dev.inmo.tgbotapi.types.rich.RichMessage] made of [dev.inmo.tgbotapi.types.rich.RichBlock]s.
|
||||
* 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.
|
||||
*
|
||||
* Key concepts demonstrated:
|
||||
* - [dev.inmo.tgbotapi.types.rich.InputRichMessage] — describes a rich message to send. Built only via
|
||||
* the [InputRichMessageHTML] / [InputRichMessageMarkdown] factories (exactly one format must be used)
|
||||
* - [sendRichMessage] — sendRichMessage method
|
||||
* - [sendRichMessageDraft] — sendRichMessageDraft method: stream partial rich messages by draftId
|
||||
* - [EditChatMessageRichText] — editMessageText with the new `rich_message` parameter
|
||||
* - [onRichMessage] — trigger for incoming [dev.inmo.tgbotapi.types.message.content.RichMessageContent]
|
||||
* (the new `rich_message` field of Message)
|
||||
* - [waitRichMessage] — expectation for a rich message
|
||||
* - [onlyRichMessageContentMessages] — flow filter keeping only rich message content
|
||||
* - [InputRichMessageContent] — usable as InputMessageContent in inline query results
|
||||
* 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.
|
||||
*
|
||||
* Telegram Bot API 10.2 additions demonstrated below:
|
||||
* - [InputRichMessageBlocks] — build a rich message from a typed [dev.inmo.tgbotapi.types.rich.InputRichBlock]
|
||||
* tree via the InputRichBlocks DSL instead of an HTML/Markdown string (exactly one of html/markdown/blocks)
|
||||
* - the draft-only `thinking()` block, streamed through [sendRichMessageDraft]
|
||||
* - [InputRichMessageMedia] — media referenced from the rich message via `tg://photo?id=` / `tg://video?id=` /
|
||||
* `tg://audio?id=`, plus first-class media blocks (photo/video/...) inside the blocks tree; new files are
|
||||
* uploaded as `attach://` automatically by [dev.inmo.tgbotapi.requests.send.SendRichMessage]
|
||||
* @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()
|
||||
|
||||
Reference in New Issue
Block a user