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

# Bot responses

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

This page describes the main response scenarios: what a regular user sees, what an administrator sees, and how the bot reacts to errors.

{% hint style="info" %}
The exact text may differ because the greeting, final messages, and buttons are configured in the admin panel. The behavior logic is described here.
{% endhint %}

### Overall flow

```mermaid
flowchart TD
    A["User writes to the bot"] --> B{"/start or a regular message?"}
    B -->|"/start"| C["Saving the user"]
    C --> D{"Is the user an administrator?"}
    D -->|No| E["Client greeting"]
    D -->|Yes| F["Greeting + admin menu"]
    B -->|"Regular message"| G["Checking limits"]
    G --> H["AI consultant"]
    H --> I["Clarification or blogger selection"]
```

### Response to `/start`

When launched, the bot saves the user's Telegram data to the database. If the user was already saved, the bot updates the username, first name, and last name.

After that, the bot checks the user's Telegram ID in the list of administrators.

{% tabs %}
{% tab title="Regular user" %}
The user receives a greeting, a button to open the catalog, and can send a request for AI selection.
{% endtab %}

{% tab title="Administrator" %}
The administrator receives the standard greeting, then an additional message about entering admin mode and the control keyboard.
{% endtab %}
{% endtabs %}

### Greeting

The greeting can come from two sources:

* `web_welcome` - settings saved through the web admin panel;
* `bot` - a greeting configured by the administrator through the Telegram menu.

If no greeting is configured, the bot sends a standard text: it introduces itself as an AI consultant and offers to describe the task or open the full catalog.

<details>

<summary>How greeting media is sent</summary>

An image or video can be attached to the greeting. If Telegram does not accept HTML markup together with a media message, the bot resends it in a simpler way: plain text or a caption without HTML mode.

</details>

### Catalog open button

The catalog button opens the Mini App. Usually it uses `MINI_APP_LINK` or the placeholder `{MINI_APP_LINK}`.

If the button leads to the catalog, the bot sends it as a Telegram Web App button. If the button leads to an external site, it is sent as a regular link.

{% hint style="success" %}
For the user, it looks just as simple: they click the button and go to the catalog. Inside Telegram, the bot automatically chooses the correct type of button.
{% endhint %}

### Response to a regular message

The bot treats a regular text message as a request to the AI consultant.

Before contacting the AI, the bot checks the limits:

* the message must not be longer than 1000 characters;
* messages must not be sent too frequently;
* admin commands from the keyboard must not be sent to the AI.

If the message is too long, the bot asks to shorten the request. If the user writes too often, the bot asks them to wait a little.

### First AI response

In a new dialog, the first response is usually clarifying. Even if the request already seems clear, the bot must gather context: niche, budget, target audience, integration format, and the goal of the ad.

{% hint style="warning" %}
This is done deliberately: the bot should not immediately provide a random list of bloggers without understanding the client's task.
{% endhint %}

### Blogger selection

When there is enough data, the AI returns a list of suitable bloggers. Usually a maximum of three recommendations is used.

The bot checks each name in the database and sends the user:

* an introductory message from the AI;
* a blogger card;
* a personalized description tailored to the client's request;
* an image, if the file exists in the project;
* a link to statistics, if it is filled in.

<details>

<summary>What happens if the AI returns a blogger that is not in the database</summary>

The bot does not send a made-up card. Instead, it falls back to a backup scenario and shows several bloggers from the database.

</details>

### Final message

After the cards, the bot sends a final message. Its text is stored in the setting `BOT_CONTACT_TEXT`, and the buttons are in `BOT_FINAL_BUTTONS`.

Supported placeholders:

| Placeholder        | What is inserted                               |
| ------------------ | ---------------------------------------------- |
| `{TEXT}`           | Ready-made request text with selected bloggers |
| `{AGENCY_LINK}`    | Agency link                                    |
| `{DEVELOPER_LINK}` | Link to the developer or technical contact     |
| `{MINI_APP_LINK}`  | Link to the Mini App catalog                   |

### AI errors

{% tabs %}
{% tab title="No key" %}
If the AI API key is not configured, the bot says that AI is temporarily unavailable.
{% endtab %}

{% tab title="Provider error" %}
If the AI provider returned an error, the bot reports the problem and asks to try again later.
{% endtab %}

{% tab title="No selection" %}
If the AI did not return a list of bloggers, the bot sends a clarifying response or a regular text response without cards.
{% endtab %}
{% endtabs %}

### Mailings

The mailing is sent to users who launched the bot and are saved in the database.

The message can be text, photo, or video. A button can be added to it.

After sending, the bot saves the result:

* `success` - the message was sent;
* `blocked` - the user blocked the bot;
* `error` - another sending error occurred.

### Posts in the channel

The administrator can prepare a post and send it to the Telegram channel. The bot copies the administrator's message and publishes it to the channel with a button, if one was added.

To publish, the configured `CHANNEL_ID`is required, and the bot must be an administrator of the channel.

### Responses to the administrator

The administrator sees a separate keyboard with quick actions: mailing, channel post, statistics, Excel export, greeting setup, final buttons, and a link to the web admin panel.


---

# 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/telegram-bot/bot-responses.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.