> 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/arkhitektura/telegram-bot.md).

# Telegram бот

Telegram-бот - это отдельный процесс внутри каждой языковой версии. Он отвечает на сообщения пользователей, открывает mini app, ведет AI-диалог, отправляет рассылки и публикует посты в Telegram-канал.

{% hint style="info" %}
У каждой языковой версии должен быть свой Telegram-бот и свой Telegram bot token. Один токен нельзя безопасно использовать для нескольких языковых версий.
{% endhint %}

### Где находится

Код бота находится в языковом проекте:

```
bot/
```

Основные части:

| Файл или папка          | Назначение                                    |
| ----------------------- | --------------------------------------------- |
| `bot/main.py`           | Запуск polling и перезапуск при смене токена. |
| `bot/handlers/user.py`  | Ответы обычным пользователям.                 |
| `bot/handlers/admin.py` | Админские функции внутри Telegram.            |
| `bot/ai_logic.py`       | AI-консультант.                               |
| `bot/db_services.py`    | Работа с базой.                               |
| `bot/config.py`         | Получение настроек и public URL.              |

### Как работает бот

```mermaid
flowchart TB
    A["Пользователь в Telegram"] --> B["Telegram Bot API"]
    B --> C["bot container"]
    C --> D["PostgreSQL языковой версии"]
    C --> E["AI provider"]
    C --> F["Mini App URL"]
    C --> G["Telegram-канал"]
```

Бот работает через long polling. Он получает обновления от Telegram Bot API, обрабатывает сообщения и отправляет ответы обратно через Telegram.

### Что бот хранит в базе

| Данные             | Для чего нужны                       |
| ------------------ | ------------------------------------ |
| Пользователи бота  | Рассылки и статистика.               |
| Приветствие        | Сообщение после `/start`.            |
| AI-настройки       | Провайдер, модель, API key и промпт. |
| Кнопки связи       | Финальные действия после AI-подбора. |
| Telegram admin IDs | Доступ к админским функциям в боте.  |
| Channel ID         | Публикации в Telegram-канал.         |

### Mini app button

{% tabs %}
{% tab title="При установке" %}
Установщик вызывает Telegram Bot API и настраивает системную кнопку mini app. URL строится из домена и `PUBLIC_BASE_PATH`.
{% endtab %}

{% tab title="При смене токена" %}
Когда токен меняется в админке, backend сначала пытается настроить кнопку mini app у нового бота. Если Telegram возвращает ошибку, токен не сохраняется.
{% endtab %}

{% tab title="Внутри /start" %}
В приветствии бот может показывать inline-кнопку открытия каталога. Она ведет на mini app текущей языковой версии.
{% endtab %}
{% endtabs %}

### AI-консультант

<details>

<summary>Что делает AI-консультант</summary>

AI-консультант ведет диалог с пользователем, уточняет задачу рекламной кампании, подбирает блогеров из базы текущей языковой версии и показывает финальные кнопки связи.

Он не должен придумывать блогеров вне базы. Его задача - предложить конкретные карточки из каталога.

</details>

<details>

<summary>Что влияет на ответы</summary>

На ответы влияют карточки в базе, описания блогеров, настройки AI-провайдера, модель, системный промпт и язык текущей версии.

</details>

### Админские функции в боте

Администратор может работать с ботом прямо в Telegram, если его Telegram ID добавлен в список админов.

{% hint style="warning" %}
Логин в web-админку и Telegram admin ID - разные вещи. Web-админка проверяет логин и пароль, а бот проверяет Telegram ID пользователя.
{% endhint %}

### Публикации и рассылки

| Возможность  | Как работает                                                       |
| ------------ | ------------------------------------------------------------------ |
| Рассылка     | Отправляется пользователям, которые запускали бота текущей версии. |
| Пост в канал | Бот публикует сообщение в канал по сохраненному `CHANNEL_ID`.      |
| Статистика   | База хранит общее число пользователей и статус блокировки.         |

Для публикации в канал бот должен быть администратором этого канала.


---

# 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/arkhitektura/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.