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

# Role

The Telegram bot is the Telegram entry point to the platform. Through it, the client opens the showcase, talks to the AI consultant, and gets a selection of bloggers without leaving third-party services.

{% hint style="info" %}
The bot is not a separate system. It works on top of the same database as the showcase and the web admin panel: cards, settings, greeting, AI, and Telegram parameters are taken from the shared database of the selected language version.
{% endhint %}

### Main task

The bot solves three practical tasks:

* bring the client from Telegram into the catalog;
* help the client choose bloggers through the AI consultant;
* give the owner quick Telegram tools for mailings, posts, and statistics.

```mermaid
flowchart TD
    A["Telegram user"] --> B["Telegram bot"]
    B --> C["Greeting"]
    C --> D["Mini App with the showcase"]
    C --> E["AI consultant"]
    E --> F["Blogger cards from the database"]
    B --> G["Admin mode"]
    G --> H["Mailings, posts, statistics"]
```

### For the client and the owner

{% tabs %}
{% tab title="Client" %}
The client launches the bot, receives a greeting, and can immediately open the catalog inside Telegram.

If the client does not want to search manually, they send a regular message: niche, budget, geography, target audience, or advertising campaign goal. The bot asks for details and suggests suitable bloggers from the database.
{% endtab %}

{% tab title="Owner" %}
The owner gets a Telegram sales channel on top of the showcase.

The bot saves users who launched it, helps send mailings, publish posts to the channel, view statistics, and quickly go to the web admin panel.
{% endtab %}

{% tab title="Administrator" %}
The administrator can work directly from Telegram if their Telegram ID is added to the list of administrators.

After `/start` the bot will show an additional keyboard with quick actions: mailings, posts, greeting, statistics, Excel export, and a link to the web admin panel.
{% endtab %}
{% endtabs %}

### Connection with the showcase

The showcase opens in Telegram as a Mini App. It is the same Bloggers Bot Platform catalog that is available in the browser, but opened inside Telegram.

The Mini App button can be located:

* in the Telegram bot system menu;
* in the greeting message;
* in the final buttons after AI selection;
* in custom buttons that use the catalog link.

{% hint style="success" %}
If the button specifies the placeholder `{MINI_APP_LINK}`, the bot replaces it with the current showcase address for the current language version.
{% endhint %}

<details>

<summary>How the bot understands that the button should open as a Mini App</summary>

If the link matches the showcase address or contains `{MINI_APP_LINK}`, the bot sends the button as a Telegram Web App button. Such a button opens the catalog inside Telegram.

If the link leads to another external site, it is sent as a regular inline button.

</details>

### Connection with the admin panel

The main bot settings are changed in the web admin panel:

* Telegram bot token;
* channel ID for publishing;
* greeting;
* greeting media file;
* greeting buttons;
* AI provider, key, model, and prompt;
* final text after AI selection;
* final buttons;
* list of Telegram administrator IDs.

After saving, the settings go into the database. The bot reads them from the database and uses them without separate manual file editing.

### AI consultant

The AI consultant is needed so the client does not have to manually study the entire catalog. It asks clarifying questions and selects bloggers for the client's task.

{% hint style="warning" %}
The AI consultant must not invent bloggers. It works with cards that already exist in the database. If the required blogger is not in the database, the bot will not be able to display their card correctly.
{% endhint %}

<details>

<summary>What happens during blogger selection</summary>

The bot passes the AI a description of the client's task and the available list of bloggers. The AI returns suitable names, and the bot checks them against the database.

If matches are found, the user receives the cards. If the AI returns names that are not in the database, a fallback scenario is triggered: the bot shows several bloggers from the catalog.

</details>

### Admin mode

Admin mode is enabled not by a password, but by the user's Telegram ID. This is a separate access that is not tied to the login and password of the web admin panel.

```mermaid
flowchart LR
    A["/start"] --> B{"Is the Telegram ID in ADMIN_IDS?"}
    B -->|No| C["Regular client flow"]
    B -->|Yes| D["Greeting + admin keyboard"]
```

<details>

<summary>Why Telegram ID is more important than username</summary>

A Telegram username can be changed. A Telegram ID remains constant and uniquely identifies the user. Therefore, admin access is granted specifically by ID.

</details>

### What is important to understand

The bot does not replace the web admin panel and is not a separate CRM. Its role is to be the client and operational Telegram channel on top of the project's shared database.

The bot's main technical key is the Telegram bot token. Without it, the bot will not be able to connect to the Telegram API, receive messages, send mailings, configure the Mini App, or publish posts.


---

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