> 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/otvety-bota.md).

# Ответы бота

Replace your auto-generated subdomain with your own domain, with automatic SSL.

Эта страница описывает основные сценарии ответов: что видит обычный пользователь, что видит администратор и как бот реагирует на ошибки.

{% hint style="info" %}
Точные тексты могут отличаться, потому что приветствие, финальные сообщения и кнопки настраиваются в админ-панели. Здесь описана логика поведения.
{% endhint %}

### Общая схема

```mermaid
flowchart TD
    A["Пользователь пишет боту"] --> B{"/start или обычное сообщение?"}
    B -->|"/start"| C["Сохранение пользователя"]
    C --> D{"Пользователь администратор?"}
    D -->|Нет| E["Приветствие клиента"]
    D -->|Да| F["Приветствие + админское меню"]
    B -->|"Обычное сообщение"| G["Проверка ограничений"]
    G --> H["AI-консультант"]
    H --> I["Уточнение или подбор блогеров"]
```

### Ответ на `/start`

При запуске бот сохраняет Telegram-данные пользователя в базе. Если пользователь уже был сохранен, бот обновляет username, имя и фамилию.

После этого бот проверяет Telegram ID пользователя в списке администраторов.

{% tabs %}
{% tab title="Обычный пользователь" %}
Пользователь получает приветствие, кнопку открытия каталога и может написать запрос для AI-подбора.
{% endtab %}

{% tab title="Администратор" %}
Администратор получает обычное приветствие, а затем дополнительное сообщение о входе в админский режим и клавиатуру управления.
{% endtab %}
{% endtabs %}

### Приветствие

Приветствие может приходить из двух источников:

* `web_welcome` - настройки, сохраненные через веб-админку;
* `bot` - приветствие, настроенное администратором через Telegram-меню.

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

<details>

<summary>Как отправляется приветственное медиа</summary>

К приветствию можно прикрепить изображение или видео. Если Telegram не принимает HTML-разметку вместе с media-сообщением, бот повторяет отправку более простым способом: обычным текстом или caption без HTML-режима.

</details>

### Кнопка открытия каталога

Кнопка каталога открывает Mini App. Обычно она использует `MINI_APP_LINK` или плейсхолдер `{MINI_APP_LINK}`.

Если кнопка ведет на каталог, бот отправляет ее как Telegram Web App button. Если кнопка ведет на внешний сайт, она отправляется как обычная ссылка.

{% hint style="success" %}
Для пользователя это выглядит одинаково просто: он нажимает кнопку и попадает в каталог. Внутри Telegram бот сам выбирает правильный тип кнопки.
{% endhint %}

### Ответ на обычное сообщение

Обычное текстовое сообщение бот воспринимает как запрос к AI-консультанту.

Перед обращением к AI бот проверяет ограничения:

* сообщение не должно быть длиннее 1000 символов;
* сообщения нельзя отправлять слишком часто;
* админские команды из клавиатуры не должны уходить в AI.

Если сообщение слишком длинное, бот просит сократить запрос. Если пользователь пишет слишком часто, бот просит немного подождать.

### Первый ответ AI

В новом диалоге первый ответ обычно уточняющий. Даже если запрос уже выглядит понятным, бот должен собрать контекст: нишу, бюджет, целевую аудиторию, формат интеграции и цель рекламы.

{% hint style="warning" %}
Это сделано специально: бот не должен сразу выдавать случайный список блогеров без понимания задачи клиента.
{% endhint %}

### Подбор блогеров

Когда данных достаточно, AI возвращает список подходящих блогеров. Обычно используется максимум три рекомендации.

Бот проверяет каждое название в базе и отправляет пользователю:

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

<details>

<summary>Что будет, если AI вернул блогера, которого нет в базе</summary>

Бот не отправляет выдуманную карточку. Вместо этого он включает запасной сценарий и показывает несколько блогеров из базы.

</details>

### Финальное сообщение

После карточек бот отправляет финальное сообщение. Его текст хранится в настройке `BOT_CONTACT_TEXT`, а кнопки - в `BOT_FINAL_BUTTONS`.

Поддерживаются плейсхолдеры:

| Плейсхолдер        | Что подставляется                              |
| ------------------ | ---------------------------------------------- |
| `{TEXT}`           | Готовый текст заявки с выбранными блогерами    |
| `{AGENCY_LINK}`    | Ссылка на агентство                            |
| `{DEVELOPER_LINK}` | Ссылка на разработчика или технический контакт |
| `{MINI_APP_LINK}`  | Ссылка на каталог Mini App                     |

### Ошибки AI

{% tabs %}
{% tab title="Нет ключа" %}
Если AI API key не настроен, бот сообщает, что AI временно недоступен.
{% endtab %}

{% tab title="Ошибка провайдера" %}
Если AI-провайдер вернул ошибку, бот сообщает о проблеме и просит попробовать позже.
{% endtab %}

{% tab title="Нет подбора" %}
Если AI не выдал список блогеров, бот отправляет уточняющий ответ или обычный текстовый ответ без карточек.
{% endtab %}
{% endtabs %}

### Рассылки

Рассылка отправляется пользователям, которые запускали бота и сохранены в базе.

Сообщение может быть текстом, фото или видео. К нему можно добавить кнопку.

После отправки бот сохраняет результат:

* `success` - сообщение отправлено;
* `blocked` - пользователь заблокировал бота;
* `error` - возникла другая ошибка отправки.

### Посты в канал

Администратор может подготовить пост и отправить его в Telegram-канал. Бот копирует сообщение администратора и публикует его в канал с кнопкой, если она была добавлена.

Для публикации нужен настроенный `CHANNEL_ID`, а бот должен быть администратором канала.

### Ответы администратору

Администратор видит отдельную клавиатуру с быстрыми действиями: рассылка, пост в канал, статистика, Excel-выгрузка, настройка приветствия, финальные кнопки и ссылка на веб-админку.


---

# 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/otvety-bota.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.