> For the complete documentation index, see [llms.txt](https://vitrina-blogerov.gitbook.io/bloggers-showcase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vitrina-blogerov.gitbook.io/bloggers-showcase/product-docs/product-docs-en/architecture/telegram-bot.md).

# Telegram bot

A Telegram bot is a separate process within each language version. It responds to user messages, opens the mini app, runs AI conversations, sends mailings, and publishes posts to the Telegram channel.

{% hint style="info" %}
Each language version must have its own Telegram bot and its own Telegram bot token. One token cannot be safely used for multiple language versions.
{% endhint %}

### Where it is located

The bot code is located in the language project:

```
bot/
```

Main parts:

| File or folder          | Purpose                                                 |
| ----------------------- | ------------------------------------------------------- |
| `bot/main.py`           | Starting polling and restarting when the token changes. |
| `bot/handlers/user.py`  | Replies to regular users.                               |
| `bot/handlers/admin.py` | Admin functions inside Telegram.                        |
| `bot/ai_logic.py`       | AI consultant.                                          |
| `bot/db_services.py`    | Working with the database.                              |
| `bot/config.py`         | Retrieving settings and the public URL.                 |

### How the bot works

```mermaid
flowchart TB
    A["User in Telegram"] --> B["Telegram Bot API"]
    B --> C["bot container"]
    C --> D["PostgreSQL of the language version"]
    C --> E["AI provider"]
    C --> F["Mini App URL"]
    C --> G["Telegram channel"]
```

The bot works via long polling. It receives updates from the Telegram Bot API, processes messages, and sends replies back through Telegram.

### What the bot stores in the database

| Data               | What they are used for                |
| ------------------ | ------------------------------------- |
| Bot users          | Mailings and statistics.              |
| Greeting           | Message after `/start`.               |
| AI settings        | Provider, model, API key, and prompt. |
| Contact buttons    | Final actions after AI selection.     |
| Telegram admin IDs | Access to admin functions in the bot. |
| Channel ID         | Posts to the Telegram channel.        |

### Mini app button

{% tabs %}
{% tab title="When installed" %}
The installer calls the Telegram Bot API and configures the system mini app button. The URL is built from the domain and `PUBLIC_BASE_PATH`.
{% endtab %}

{% tab title="When the token changes" %}
When the token is changed in the admin panel, the backend first tries to configure the mini app button for the new bot. If Telegram returns an error, the token is not saved.
{% endtab %}

{% tab title="Inside /start" %}
In the greeting, the bot can show an inline button to open the catalog. It leads to the mini app of the current language version.
{% endtab %}
{% endtabs %}

### AI consultant

<details>

<summary>What the AI consultant does</summary>

The AI consultant carries on a conversation with the user, clarifies the task of the advertising campaign, selects bloggers from the current language version's database, and shows the final contact buttons.

It should not invent bloggers outside the database. Its task is to suggest specific cards from the catalog.

</details>

<details>

<summary>What affects the responses</summary>

The responses are affected by the cards in the database, blogger descriptions, AI provider settings, the model, the system prompt, and the language of the current version.

</details>

### Admin functions in the bot

The administrator can work with the bot directly in Telegram if their Telegram ID is added to the admin list.

{% hint style="warning" %}
The login to the web admin panel and the Telegram admin ID are different things. The web admin panel checks the login and password, while the bot checks the user's Telegram ID.
{% endhint %}

### Posts and mailings

| Feature      | How it works                                                             |
| ------------ | ------------------------------------------------------------------------ |
| Mailing      | Sent to users who have launched the bot of the current version.          |
| Channel post | The bot publishes a message to the channel using the saved `CHANNEL_ID`. |
| Statistics   | The database stores the total number of users and their block status.    |

To publish to the channel, the bot must be an administrator of that channel.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vitrina-blogerov.gitbook.io/bloggers-showcase/product-docs/product-docs-en/architecture/telegram-bot.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.