# Введение

Botads — рекламная платформа для Телеграм ботов и мини‑приложений.

## Поддерживаемые сценарии

Мы предлагаем два формата монетизации, которые дополняют друг друга:

### 1. Rewarded (Web App)

Интерактивный формат через Telegram Mini Apps.

* **Сценарий:** Бот отправляет пользователю кнопку «Смотреть рекламу» (или «Получить бонус»).
* **Действие:** Открывается мини-приложение, пользователь смотрит ролик.
* **Результат:** После закрытия рекламы вы получаете вебхук `rewarded` и начисляете награду пользователю.

### 2. Direct Link (Короткая ссылка)

Универсальный формат, работающий везде (включая старые клиенты и Telegram X).

* **Сценарий:** Бот генерирует уникальную короткую ссылку для конкретного пользователя.
* **Действие:** Пользователь переходит по ссылке.
* **Результат:** Мы фиксируем переход и отправляем вебхук `direct_link`.

> **Рекомендация:** Используйте связку обоих форматов.
>
> 1. Сделайте **основной кнопкой** открытие Web App. Показ рекламы без выхода из мессенджера значительно снижает число отказов (bounce rate) и повышает конверсию.
> 2. Добавьте **запасную кнопку** (или текстовую ссылку) с Direct Link. Часть пользователей использует неофициальные клиенты или устаревшие версии Telegram, которые не поддерживают Mini Apps. Заранее узнать возможности клиента невозможно, поэтому запасной вариант гарантирует 100% охват аудитории.

***

## Ключевые компоненты интеграции

При подключении бота вы получаете два важных параметра: `API Token` и `Bot Prefix` (числовой `prefix_seq`).

### 1. API Token

Секретный ключ для доступа к **Client API**. Используйте его на своем сервере для генерации ссылок.

* **Endpoint:** `https://api.botads.app`

### 2. Домены

В зависимости от выбранного сценария, вы используете разные домены:

| Сценарий        | Какой URL формировать                     | Описание                                                                              |
| --------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
| **Direct Link** | `https://ads.botads.app/{code}`           | Глобальный домен редиректов. `{code}` вы получаете через API.                         |
| **Rewarded**    | `https://{prefix_seq}.miniapp.botads.app` | Персональный домен **для каждого** Web App. `{prefix_seq}` — ваш числовой Bot Prefix. |

***

## Быстрый старт

1. **Установите SDK** (пока доступен Python):

   ```bash
   pip install botads-sdk
   ```
2. **Сгенерируйте Direct Link** (пример на Python):

   ```python
   from botads import BotadsClient

   # Инициализация с вашим токеном
   client = BotadsClient(base_url="https://api.botads.app", api_token="YOUR_API_TOKEN")

   # Запрос кода для конкретного юзера (user_tg_id)
   response = client.create_code(bot_id="123456789", user_tg_id="799001234")

   # Формирование ссылки для отправки пользователю
   print(f"Ваша ссылка: https://ads.botads.app/{response.code}")
   ```
3. **Или используйте cURL**:

   ```bash
   curl -X POST https://api.botads.app/client/v1/codes \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"bot_id": "123456789", "user_tg_id": "799001234"}'
   ```
4. **Обработайте Вебхук**: Настройте endpoint на своем сервере для приема `POST` запросов. Проверяйте подпись `X-Signature` (см. раздел Вебхуки), чтобы защититься от фрода.

***

## Документация

* [Client API](/client-api.md) — методы API, создание кодов.
* [SDK](/overview.md) — библиотеки для быстрой интеграции.
* [Вебхуки](/webhooks.md) — формат уведомлений и проверка безопасности.
* [Ошибки и лимиты](/errors.md) — справочник кодов ответов.
* [FAQ](/faq.md) — ответы на частые вопросы.

**Нужна помощь?** Пишите в поддержку: [t.me/BotAdsTechSupport](https://t.me/BotAdsTechSupport)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.botads.app/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.