# 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. Bot API 10.3 coverage includes rich
buttons, compact tables, expandable quotations, document blocks, document
references, direct document uploads, and stoppable drafts.

## Commands

The bot installs eight 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_10_3` | Yes | Sends an inline `RichTextButton`, three aligned `InputRichBlockButtons` rows with URL, callback, inline-query, copy-text, and disabled actions, a compact table, an expandable quotation, and a document block. |
| `/rich_draft` | Yes | In a private chat, streams three Markdown revisions with `canStop` and `keepOnStop`, one second apart, then sends a normal final rich message unless generation is stopped. |
| `/rich_blocks_draft` | Yes | In a private chat, streams two draft-only `thinking()` blocks with `canStop` and `keepOnStop`, then sends a normal typed-block answer unless generation is stopped. |
| `/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 allocate a unique draft ID and subscribe to
`waitMessageGenerationStopped` before sending the first revision. They finalize
by sending a new normal rich message only if no matching stop update arrives;
when stopped, they leave the retained draft untouched and log the event.

## 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 document | Reuses the received file ID through a `tg://document?id=userdocument` HTML reference, then downloads the file and sends it again as a multipart upload nested in a typed `document()` block. Large documents are therefore held in memory. |
| A `rich_10_3_callback` rich button | Answers the callback with a notification confirming that the rich-message button was received. |
| 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, document, collage, and slideshow blocks.
The document trigger demonstrates the library collecting a multipart file nested
in a rich-message tree as an `attach://` upload.

## 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, document, 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"
```