RocketlyAPI · v1
Интеграция

Подключите бота к Rocketly: задания, обязательная подписка и отписки через один API

Ваш бот показывает пользователям задания на подписку и/или просит подписаться перед использованием. Rocketly собирает задания из нескольких сетей, проверяет выполнение и присылает вашему боту события — в том числе об отписках, чтобы вы отозвали награду.

Как это работает

  1. Пользователь открывает задания в вашем боте. Бот вызывает GET /v1/tasks.
  2. Бот показывает каждое задание кнопкой-ссылкой из поля url и кнопку «Проверить».
  3. Пользователь подписывается и жмёт «Проверить» — бот вызывает POST /v1/tasks/{id}/check.
  4. Ответ confirmed — бот выдаёт награду, но замораживает её на 3 дня.
  5. Если пользователь отписался, сторонняя сеть сообщает Rocketly, а Rocketly пересылает событие task.reverted на вебхук именно вашего бота. Вы забираете награду.
Подписка засчитана без «Проверить». Если человек закрыл бота и не нажал кнопку, но подписался, сеть сообщит нам, и вы получите task.confirmed событием. Награда не потеряется.

Подключение за 4 шага

  1. Откройте @nanozadbot → «Подключить бота» → пришлите токен вашего бота из @BotFather. Токен нужен один раз для проверки владельца и не сохраняется.
  2. Дождитесь одобрения администратора — решение придёт сообщением в боте.
  3. Сохраните API-ключ на сервере бота. Он показывается один раз; перевыпустить можно в карточке бота.
  4. Добавьте запросы ниже и (рекомендуется) задайте вебхук: «Мои боты» → ваш бот → «Задать вебхук».

Ключ и общие правила

Адрес APIhttps://rocketly.duckdns.org
АвторизацияЗаголовок Authorization: Bearer ВАШ_КЛЮЧ в каждом запросе
Где хранить ключТолько на сервере бота (переменная окружения). Не отдавайте его пользователям и в Mini App.
Пользовательtelegram_user_id берите из апдейта Telegram (message.from_user.id), а не из текста пользователя.
ФорматJSON, ошибки: {"error": "код"} и HTTP-статус

Получить задания

GET/v1/tasks — вызывайте, когда пользователь открывает раздел заданий. Пока задания действуют, повторный вызов возвращает те же.

ПараметрОбяз.Что это
telegram_user_idдаTelegram ID пользователя
language_codeнетЯзык из Telegram, например ru. Сети подбирают задания по языку
first_name, usernameнетИмя и username — нужны части сетей
is_premiumнетtrue / false
curl "https://rocketly.duckdns.org/v1/tasks?telegram_user_id=123456789&language_code=ru" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"
{
  "tasks": [
    {"id": "Xk3b…", "title": "Крипто Новости",
     "url": "https://rocketly.duckdns.org/go/Xk3b…", "link": "https://t.me/crypto_news",
     "source": "tgrass", "kind": "subscribe channel",
     "expires_at": 1763000000, "status": "issued"}
  ],
  "diagnostics": [],
  "empty_reason": null
}
ПолеЧто это
idНомер задания. Нужен для проверки и чтобы не выдать награду дважды
titleНазвание для кнопки
urlСсылка для кнопки. Используйте именно её (она ведёт на нужную страницу сети)
linkПрямая ссылка на канал — только для справки
sourceОткуда задание: boostly, tgrass, flowly, piarflow
expires_atДо какого времени (Unix) задание действует

empty_reason: "tasks_disabled" — в боте «Rocketly → Сторонние интеграции» выбран режим «Обязательная подписка», выдача заданий выключена. Режим один: либо задания, либо ОП.

Сколько заданий приходит за запрос, сколько берётся у одной сети, как часто набор обновляется и в каком порядке опрашиваются сети — настраивается там же. Сети с высоким приоритетом опрашиваются первыми.

empty_reason: "no_available_tasks" — заданий для этого человека сейчас нет. В diagnostics — сети, которые не ответили (остальные задания всё равно приходят).

Проверить выполнение

POST/v1/tasks/{id}/check — по кнопке «Проверить». Можно вызывать сколько угодно раз: засчитается один раз.

curl -X POST "https://rocketly.duckdns.org/v1/tasks/Xk3b…/check" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"telegram_user_id": 123456789}'
{"id": "Xk3b…", "status": "confirmed", "credited": false, "payout": "held", "release_at": 1763259200}
{"id": "Xk3b…", "status": "incomplete", "credited": false}
statusЧто значитЧто делать боту
confirmedПодписка засчитана. release_at — когда заморозка кончитсяВыдать награду один раз на этот id и заморозить до release_at
incompleteПодписки пока нетПопросить подписаться и нажать ещё раз
pendingСеть подтвердит позжеНичего: придёт событие task.confirmed
verification_errorTelegram или сеть не ответили (retryable: true)Предложить повторить через минуту
rejectedАнтифрод: твинк или ботНаграду не давать
unavailableЗадание закончилось или время вышлоПоказать новые задания
revertedПользователь отписалсяНаграду не давать (или забрать)
not_countedВыполнено, но сеть это не засчиталаЛучше без награды

Проверить все сразу

POST/v1/tasks/check_all — для кнопки «Проверить все». Проверяет все выданные пользователю задания за один вызов.

curl -X POST "https://rocketly.duckdns.org/v1/tasks/check_all" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"telegram_user_id": 123456789}'
{"results": [{"id": "Xk3b…", "status": "confirmed", "credited": false, "payout": "held", "release_at": 1763259200},
             {"id": "Qw9z…", "status": "incomplete", "credited": false}],
 "total": 2, "confirmed": 1, "incomplete": 1, "unavailable": 0, "errors": 0}

Каждый элемент results — ответ как у одиночной проверки. Если total = 0 — выданных заданий нет, запросите /v1/tasks заново.

События

GET/v1/events?after_sequence=N — лента всего, что случилось с заданиями вашего бота. До 100 событий за раз. Сохраняйте sequence последнего обработанного и передавайте его в after_sequence. Опрашивайте каждые 15–60 секунд, либо подключите вебхук ниже.

[{
  "sequence": 41, "id": "task:Xk3b…", "created_at": "2026-11-20 14:05:11",
  "payload": {"event": "task.confirmed", "task_id": "Xk3b…", "telegram_user": 123456789,
              "source": "tgrass", "payout": "held", "release_at": 1763259200}
}]
payload.eventКогда приходит
task.confirmedПодписка засчитана (кнопкой или автоматически). Выдайте награду, если ещё не выдали
task.revertedПользователь отписался. Поле reason: unsubscribed_during_hold — отписался в период заморозки, награду забрать; unsubscribed_after_hold — после заморозки, награда остаётся у пользователя
task.not_countedСеть отменила начисление (фейк-аккаунт, неверный язык, переход с другой ссылки…). Забрать награду. Причина в reason
op: trueВ любом событии: задание из обязательной подписки — награду за него не выдавайте

Событие может прийти повторно — обрабатывайте по id (или task_id) один раз.

Вебхук вместо опроса

Если у бота есть HTTPS-адрес с доменным именем, Rocketly сам присылает каждое событие POST-запросом, в том числе об отписках. Лента /v1/events продолжает работать: из неё можно забрать недоставленное. Адрес можно задать в боте (карточка бота → «Задать вебхук») или API:

PUT /v1/webhookТело {"url": "https://…"}. В ответе webhook_secret: каждый вызов выдаёт новый
GET /v1/webhookАдрес, сколько событий ждёт доставки, число ошибок
POST /v1/webhook/testОтправить тестовое событие webhook.test
DELETE /v1/webhookОтключить вебхук
import hashlib, hmac, time

def hub_signed(body: bytes, headers, secret: str) -> bool:
    stamp = headers.get("X-Hub-Timestamp", "")
    if not stamp.isdigit() or abs(time.time() - int(stamp)) > 300:
        return False
    exp = "sha256=" + hmac.new(secret.encode(), stamp.encode() + b"." + body,
                               hashlib.sha256).hexdigest()
    return hmac.compare_digest(exp, headers.get("X-Hub-Signature", ""))

Награда пользователю и штрафы за отписки

Что пришлоНаграда
confirmed / task.confirmedВыдать один раз и заморозить
rejected, task.not_countedНе выдавать / забрать
task.reverted: unsubscribed_during_holdЗабрать
task.reverted: unsubscribed_after_holdОставить
verification_error (retryable)Не трогать, проверить позже
incomplete / pendingНе выдавать, пока не придёт confirmed

Выплаты владельцу бота

Это деньги платформы вам, а не награда вашим пользователям (о ней — раздел выше).

Обязательная подписка (ОП)

Пользователь подписывается на каналы спонсоров, прежде чем пользоваться ботом. Какие сети участвуют в ОП, выбирает администратор платформы, а порядок сетей и режим — вы в «Сторонние интеграции». Включить нужно режим «Обязательная подписка»: в режиме «Задания» /v1/gate всегда отвечает {"access": true}.

GET/v1/gate?telegram_user_id=…&language_code=… — вызывайте перед ответом на каждое сообщение.

{"access": true}
{"access": false, "text": "Чтобы пользоваться ботом, подпишитесь…",
 "tasks": [{"id": "Xk3b…", "title": "Канал", "url": "https://rocketly.duckdns.org/go/Xk3b…", "kind": "subscribe channel"}]}

POST/v1/gate/check с телом {"telegram_user_id": …} — кнопка «Проверить». access: true — пропустите человека; false — в tasks то, что ещё не выполнено.

События по ОП-заданиям приходят с op: true — награду за них не выдавайте. Отписки от ОП-каналов тоже пересылаются событием task.reverted: можно, например, снова закрыть доступ.

Ошибки

КодЧто делать
400Проверьте поля запроса (telegram_user_id_required, https_domain_required)
401missing_key / invalid_key: проверьте заголовок и что ключ не перевыпущен
403platform_not_active: бот ещё не одобрен или отклонён
404Задание не найдено или выдано не этому пользователю

Готовый код (Python, aiogram)

import asyncio, httpx

API = "https://rocketly.duckdns.org"
H = {"Authorization": "Bearer ВАШ_КЛЮЧ"}
http = httpx.AsyncClient(timeout=10)

async def get_tasks(user):
    r = await http.get(f"{API}/v1/tasks", headers=H, params={
        "telegram_user_id": user.id, "language_code": user.language_code or "ru",
        "first_name": user.first_name, "username": user.username or "",
        "is_premium": str(bool(user.is_premium)).lower()})
    return r.json()["tasks"] if r.status_code == 200 else []

async def check_task(user_id, task_id):
    r = await http.post(f"{API}/v1/tasks/{task_id}/check", headers=H,
                        json={"telegram_user_id": user_id})
    return r.json()          # status == "confirmed" → награда + заморозка на 3 дня

async def check_all(user_id, task_ids):   # кнопка «Проверить все» — те же запросы /check, по всем заданиям разом
    res = await asyncio.gather(*[check_task(user_id, t) for t in task_ids], return_exceptions=True)
    return [x for x in res if isinstance(x, dict)]   # у каждого свой status (confirmed / incomplete / …)

async def gate(user):        # перед ответом на КАЖДОЕ сообщение
    try:
        r = await http.get(f"{API}/v1/gate", headers=H, timeout=3, params={
            "telegram_user_id": user.id, "language_code": user.language_code or "ru"})
        return r.json() if r.status_code == 200 else {"access": True}
    except httpx.HTTPError:
        return {"access": True}

# Приём вебхука (aiohttp): проверьте подпись hub_signed(...) и ответьте 2xx
async def on_webhook(request):
    body = await request.read()
    if not hub_signed(body, request.headers, WEBHOOK_SECRET):
        return web.Response(status=403)
    ev = json.loads(body)
    p = ev["payload"]
    if p["event"] == "task.confirmed" and not p.get("op"):
        await grant_reward_once(p["telegram_user"], p["task_id"], hold_until=p["release_at"])
    elif p["event"] in ("task.reverted", "task.not_counted") and not p.get("op"):
        if p.get("reason") != "unsubscribed_after_hold":
            await take_back_reward(p["task_id"])        # штраф за отписку
    return web.Response(text="ok")