> 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/telegram-bot/rol.md).
# Роль
Telegram-бот - это Telegram-вход в платформу. Через него клиент открывает витрину, общается с AI-консультантом и получает подбор блогеров без перехода в сторонние сервисы.
{% hint style="info" %}
Бот не является отдельной системой. Он работает поверх той же базы, что витрина и веб-админка: карточки, настройки, приветствие, AI и Telegram-параметры берутся из общей базы выбранной языковой версии.
{% endhint %}
### Основная задача
Бот закрывает три практические задачи:
* привести клиента из Telegram в каталог;
* помочь клиенту подобрать блогеров через AI-консультанта;
* дать владельцу быстрые Telegram-инструменты для рассылок, постов и статистики.
```mermaid
flowchart TD
A["Пользователь Telegram"] --> B["Telegram бот"]
B --> C["Приветствие"]
C --> D["Mini App с витриной"]
C --> E["AI-консультант"]
E --> F["Карточки блогеров из базы"]
B --> G["Админский режим"]
G --> H["Рассылки, посты, статистика"]
```
### Для клиента и владельца
{% tabs %}
{% tab title="Клиент" %}
Клиент запускает бота, получает приветствие и может сразу открыть каталог внутри Telegram.
Если клиент не хочет искать вручную, он пишет обычное сообщение: нишу, бюджет, географию, целевую аудиторию или цель рекламной кампании. Бот уточняет детали и предлагает подходящих блогеров из базы.
{% endtab %}
{% tab title="Владелец" %}
Владелец получает Telegram-канал продаж поверх витрины.
Бот сохраняет пользователей, которые запускали его, помогает отправлять рассылки, публиковать посты в канал, смотреть статистику и быстро переходить в веб-админку.
{% endtab %}
{% tab title="Администратор" %}
Администратор может работать прямо из Telegram, если его Telegram ID добавлен в список администраторов.
После `/start` бот покажет дополнительную клавиатуру с быстрыми действиями: рассылки, посты, приветствие, статистика, Excel-выгрузка и ссылка на веб-админку.
{% endtab %}
{% endtabs %}
### Связь с витриной
Витрина открывается в Telegram как Mini App. Это тот же каталог Bloggers Bot Platform, который доступен в браузере, но открытый внутри Telegram.
Кнопка Mini App может находиться:
* в системном меню Telegram-бота;
* в приветственном сообщении;
* в финальных кнопках после AI-подбора;
* в пользовательских кнопках, где используется ссылка каталога.
{% hint style="success" %}
Если в кнопке указан плейсхолдер `{MINI_APP_LINK}`, бот заменяет его на актуальный адрес витрины текущей языковой версии.
{% endhint %}
Как бот понимает, что кнопку нужно открыть как Mini App
Если ссылка совпадает с адресом витрины или содержит `{MINI_APP_LINK}`, бот отправляет кнопку как Telegram Web App button. Такая кнопка открывает каталог внутри Telegram.
Если ссылка ведет на другой внешний сайт, она отправляется как обычная inline-кнопка.
### Связь с админ-панелью
Основные настройки бота меняются в веб-админке:
* Telegram bot token;
* ID канала для публикаций;
* приветствие;
* media-файл приветствия;
* кнопки приветствия;
* AI-провайдер, ключ, модель и промпт;
* финальный текст после AI-подбора;
* финальные кнопки;
* список Telegram ID администраторов.
После сохранения настройки попадают в базу. Бот читает их из базы и использует без отдельного ручного редактирования файлов.
### AI-консультант
AI-консультант нужен, чтобы клиенту не приходилось вручную изучать весь каталог. Он задает уточняющие вопросы и подбирает блогеров под задачу клиента.
{% hint style="warning" %}
AI-консультант не должен придумывать блогеров. Он работает с карточками, которые уже есть в базе. Если нужного блогера нет в базе, бот не сможет корректно показать его карточку.
{% endhint %}
Что происходит при подборе блогеров
Бот передает AI описание задачи клиента и доступный список блогеров. AI возвращает подходящие названия, а бот сверяет их с базой.
Если совпадения найдены, пользователь получает карточки. Если AI вернул названия, которых нет в базе, включается запасной сценарий: бот показывает несколько блогеров из каталога.
### Админский режим
Админский режим включается не по паролю, а по Telegram ID пользователя. Это отдельный доступ, который не связан с логином и паролем веб-админки.
```mermaid
flowchart LR
A["/start"] --> B{"Telegram ID есть в ADMIN_IDS?"}
B -->|Нет| C["Обычный клиентский сценарий"]
B -->|Да| D["Приветствие + админская клавиатура"]
```
Почему Telegram ID важнее username
Username в Telegram можно изменить. Telegram ID остается постоянным и однозначно определяет пользователя. Поэтому админский доступ выдается именно по ID.
### Что важно понимать
Бот не заменяет веб-админку и не является отдельной CRM. Его роль - быть клиентским и операционным Telegram-каналом поверх общей базы проекта.
Главный технический ключ бота - Telegram bot token. Без него бот не сможет подключиться к Telegram API, принимать сообщения, делать рассылки, настраивать Mini App и публиковать посты.
---
# 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/telegram-bot/rol.md?ask=&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.