Введение

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):

   pip install botads-sdk

2. Сгенерируйте Direct Link (пример на 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:

   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 — методы API, создание кодов.

• SDK — библиотеки для быстрой интеграции.

• Вебхуки — формат уведомлений и проверка безопасности.

• Ошибки и лимиты — справочник кодов ответов.

• FAQ — ответы на частые вопросы.

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