> For the complete documentation index, see [llms.txt](https://docs.botads.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.botads.app/readme.md).

# Введение

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](https://docs.botads.app/client-api.md) — методы API, создание кодов.
* [SDK](https://docs.botads.app/overview.md) — библиотеки для быстрой интеграции.
* [Вебхуки](https://docs.botads.app/webhooks.md) — формат уведомлений и проверка безопасности.
* [Ошибки и лимиты](https://docs.botads.app/errors.md) — справочник кодов ответов.
* [FAQ](https://docs.botads.app/faq.md) — ответы на частые вопросы.

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