Ваш бот показывает пользователям задания на подписку и/или просит подписаться перед использованием. Rocketly собирает задания из нескольких сетей, проверяет выполнение и присылает вашему боту события — в том числе об отписках, чтобы вы отозвали награду.
GET /v1/tasks.url и кнопку «Проверить».POST /v1/tasks/{id}/check.confirmed — бот выдаёт награду, но замораживает её на 3 дня.task.reverted на вебхук именно вашего бота. Вы забираете награду.task.confirmed событием. Награда не потеряется.| Адрес API | https://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_error | Telegram или сеть не ответили (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 | Отключить вебхук |
{"sequence", "id", "created_at", "payload"}. События идут по порядку.X-Hub-Timestamp и X-Hub-Signature: sha256=… — HMAC-SHA256 от строки timestamp + "." + тело секретом webhook_secret. Отклоняйте запросы старше 5 минут.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 — что придёт раньше.task_id: кнопка и событие могут сообщить об одном задании дважды.release_at). Пока она заморожена, её можно забрать без спора с пользователем.task.reverted с unsubscribed_during_hold и при task.not_counted — забирайте награду. После заморозки отписка ни на что не влияет.op: true награды нет.| Что пришло | Награда |
|---|---|
| confirmed / task.confirmed | Выдать один раз и заморозить |
| rejected, task.not_counted | Не выдавать / забрать |
| task.reverted: unsubscribed_during_hold | Забрать |
| task.reverted: unsubscribed_after_hold | Оставить |
| verification_error (retryable) | Не трогать, проверить позже |
| incomplete / pending | Не выдавать, пока не придёт confirmed |
Это деньги платформы вам, а не награда вашим пользователям (о ней — раздел выше).
task.reverted с unsubscribed_during_hold): начисление снимается и добавляется штраф. task.not_counted: начисление снимается без штрафа. После заморозки отписка баланс не меняет.Пользователь подписывается на каналы спонсоров, прежде чем пользоваться ботом. Какие сети участвуют в ОП, выбирает администратор платформы, а порядок сетей и режим — вы в «Сторонние интеграции». Включить нужно режим «Обязательная подписка»: в режиме «Задания» /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"}]}
access: true — обработайте сообщение как обычно.access: false — ответьте text, под ним кнопки-ссылки (title, url) и последней — «Проверить».access: false и пустой tasks (silent: true) — сеть сама прислала человеку свои каналы через вашего бота. Ничего не отвечайте.POST/v1/gate/check с телом {"telegram_user_id": …} — кнопка «Проверить». access: true — пропустите человека; false — в tasks то, что ещё не выполнено.
События по ОП-заданиям приходят с op: true — награду за них не выдавайте. Отписки от ОП-каналов тоже пересылаются событием task.reverted: можно, например, снова закрыть доступ.
| Код | Что делать |
|---|---|
| 400 | Проверьте поля запроса (telegram_user_id_required, https_domain_required) |
| 401 | missing_key / invalid_key: проверьте заголовок и что ключ не перевыпущен |
| 403 | platform_not_active: бот ещё не одобрен или отклонён |
| 404 | Задание не найдено или выдано не этому пользователю |
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")