Введение

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

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

1. Rewarded (мини‑приложение). Бот отправляет сообщение с кнопкой «Открыть мини‑приложение». Пользователь кликает, внутри мини‑приложения ему показывается реклама. Когда ролик досмотрен и пользователь закрывает экран, на сервер паблишера прилетает вебхук rewarded о успешном просмотре.

2. Direct link. Бот отправляет пользователю direct link (короткую ссылку). После перехода пользователя платформа отправляет паблишеру вебхук direct_link о успешном клике.

Комбинируйте оба формата: часть клиентов (например, Telegram X) может не поддерживать мини‑приложения, поэтому direct link обеспечит охват.

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

1. Установите Python SDK из PyPI:

   pip install botads-sdk

2. Создайте короткий код для пользователя:

   from botads import BotadsClient
   
   client = BotadsClient(base_url="https://api.botads.app", api_token="<api_token>")
   response = client.create_code(bot_id="123456789", user_tg_id="799001234")  # user_tg_id передайте строкой
   print(response.code, response.expires_in)

3. Или через curl:

   # api_token — выданный ключ бота (не JWT)
   curl -X POST https://api.botads.app/client/v1/codes \
     -H "Authorization: Bearer <api_token>" \
     -H "Content-Type: application/json" \
     -d '{"bot_id": "123456789", "user_tg_id": "799001234"}'

4. Обрабатывайте вебхуки direct_link и rewarded, чтобы начислять вознаграждения или продолжать сценарий бота. Пример проверки подписи:

   from botads import verify_signature, parse_webhook_payload
   
   def handle(body: bytes, signature_header: str, api_token: str):
       if not verify_signature(body, signature_header, api_token):
           raise ValueError("invalid signature")
       payload = parse_webhook_payload(body)
       return payload.event, payload.user_tg_id

   Где signature_header — значение заголовка X-Signature в формате sha256=<hex>. Полный пример FastAPI есть в sdks/python/examples/fastapi/main.py.

Дополнительно:

• Client API — структура запроса, ответы и коды ошибок.

• SDK — актуальные клиенты и планы по JS/Go.

• Вебхуки — payload, подпись и примеры проверки.

• Ошибки и лимиты — коды, статусы и рекомендации по ретраям.

• FAQ — типовые вопросы.

• Исходники Python SDK: sdks/python (репозиторий: https://gitlab.com/botads/sdks/python).

Если нужна помощь, напишите в поддержку: t.me/BotAdsTechSupport