API сервиса и примеры

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

Интеграция с получением ссылок

При таком варианте интеграции боты сами запрашивают ссылки, отправляют сообщение пользователю и проверяют результат подписки. Рекомендован для тех, кто не передаёт токен от бота.

Эндпоинт для интеграции

Для интеграции офферов достаточно использовать один HTTP-эндпоинт: он отдаёт новые офферы для пользователя и одновременно проверяет подписку.

POST https://tgrass.space/offers

Если у вас в боте задания, используйте эндпоинт https://tgrass.space/tasks

Стандартный кейс

  1. Делаем запрос и возвращаем офферы пользователю
  2. Для проверки делаем ещё один запрос на тот же эндпоинт /offers или /tasks и проверяем подписку. Результат определяется по статусу в ответе (ok, not_ok, no_offers)

Для проверки отдельного оффера можно использовать метод https://tgrass.space/check.

Передаваемые данные

В заголовок передаётся API-ключ Auth, полученный в сервисе @tgrassbot.

ПолеТипОбязательноеОписание
tg_user_idint✅Telegram ID пользователя
is_premiumbool✅Является ли пользователь подписчиком Telegram Premium
langstr✅Языковой код пользователя в Telegram, например en, ru, uk
tg_loginstr❌Username пользователя
genderstr❌Пол пользователя — male или female
exclude_channelslist[str]❌Список идентификаторов каналов, которые нужно исключить
offers_limitint❌Количество спонсоров в ответе. Имеет приоритет над настройкой в боте

Пример запроса через curl

curl -X POST https://tgrass.space/offers \
-H "Content-Type: application/json" \
-H "Auth: YOUR_API_KEY" \
-d '{
  "tg_user_id": 123456789,
  "tg_login": "username",
  "lang": "ru",
  "is_premium": false,
  "gender": "male"
}'

Пример ответа

{
  "status": "ok",
  "offers": [
    {
      "name": "Канал о крипте",
      "link": "https://t.me/cryptochannel",
      "subscribed": true,
      "type": "channel",
      "channel_id": null,
      "offer_id": 1012,
      "price": 2.5
    },
    {
      "name": "Технологии",
      "link": "https://t.me/technews",
      "subscribed": true,
      "type": "channel",
      "channel_id": "-10566012393",
      "offer_id": 1054,
      "price": 1.2
    }
  ],
  "description": "subscribed to all"
}

Данные в ответе

ПолеТипОписание
status str ok — подписался на все офферы
not_ok — не подписался на все
no_offers — нет подходящих офферов
descriptionstrТекстовое описание статуса
offerslistСписок офферов

Объекты в offers[i]

ПолеТипОписание
namestr | nullНазвание оффера (может быть пустым)
linkstrСсылка на оффер (бот, канал или внешний ресурс)
subscribedboolПодписан ли пользователь на этот оффер
type str bot — Telegram-бот
channel — Telegram-канал
resource — внешний ресурс или ссылка
folder — папка
channel_idstr | nullИдентификатор канала
offer_idintУникальный идентификатор оффера
pricefloatЦена оффера

Сброс времени обновления спонсоров

Если после выполнения задания нужно сразу получить новые офферы при запросе /offers и не ждать настраиваемое время обновления, используйте метод сброса:

POST https://tgrass.space/reset_offers
curl -X POST https://tgrass.space/reset_offers \
-H "Content-Type: application/json" \
-H "Auth: YOUR_API_KEY" \
-d '{
  "tg_user_id": 123456789
}'

После этого при следующем вызове /offers будет новый список офферов. Актуально для ботов, которые хотят выдавать задания сразу.

Пример интеграции

Пример простого бота, показывающего и проверяющего задания из Tgrass.

Код бота на Python / aiogram

import asyncio

import httpx
from aiogram import Bot, Dispatcher, Router, types
from aiogram.filters import Command
from aiogram.fsm.storage.memory import MemoryStorage
from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup

bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher(storage=MemoryStorage())
router = Router()

ALREADY_CHECKED_MESSAGES = []

@dp.message(Command("tasks"))
async def tasks_command_handler(message: types.Message):
    async with httpx.AsyncClient(verify=False) as client:
        response = await client.post(
            "https://tgrass.space/offers",
            json={
                "tg_user_id": int(message.from_user.id),
                "tg_login": message.from_user.username,
                "lang": message.from_user.language_code,
                "is_premium": message.from_user.is_premium,
            },
            headers={
                "accept": "application/json",
                "Content-Type": "application/json",
                "Auth": "YOUR_API_KEY",
            },
        )
    response_json = response.json()

    if response.status_code == 200 and response_json["status"] == "not_ok":
        kb = []
        for offer in response_json["offers"]:
            kb.append([
                InlineKeyboardButton(
                    text="Подписаться" if offer["type"] == "channel" else "Перейти",
                    url=offer["link"],
                ),
            ])
        kb.append([
            InlineKeyboardButton(text="Проверить ✅", callback_data="check_tgrass"),
        ])
        await message.answer(
            reply_markup=InlineKeyboardMarkup(inline_keyboard=kb),
            text="Выполнить задание",
        )
    else:
        await message.answer(text="На данный момент нет доступных заданий")


@router.callback_query(lambda c: c.data == "check_tgrass")
async def check_tgrass_handler(callback_query: types.CallbackQuery):
    await callback_query.answer()
    async with httpx.AsyncClient(verify=False) as client:
        response = await client.post(
            "https://tgrass.space/offers",
            json={
                "tg_user_id": int(callback_query.from_user.id),
                "tg_login": callback_query.from_user.username,
                "lang": callback_query.from_user.language_code,
                "is_premium": callback_query.from_user.is_premium,
            },
            headers={
                "accept": "application/json",
                "Content-Type": "application/json",
                "Auth": "YOUR_API_KEY",
            },
        )
    response_json = response.json()

    if response.status_code == 200 and response_json["status"] == "ok":
        await callback_query.message.answer(text="Задание успешно выполнено!")
        if callback_query.message.message_id not in ALREADY_CHECKED_MESSAGES:
            ALREADY_CHECKED_MESSAGES.append(callback_query.message.message_id)
            await send_coins_to_user()
    else:
        await callback_query.message.answer(text="Задание не выполнено!")


async def send_coins_to_user():
    ...


async def start():
    dp.include_router(router)
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(start())

Пример кода на Node.js

import TelegramBot from "node-telegram-bot-api";
import axios from "axios";
import https from "https";

const BOT_TOKEN = "YOUR_BOT_TOKEN";
const API_URL = "https://tgrass.space/offers";
const AUTH_TOKEN = "YOUR_API_KEY";

const bot = new TelegramBot(BOT_TOKEN, { polling: true });
const httpsAgent = new https.Agent({ rejectUnauthorized: false });
const ALREADY_CHECKED_MESSAGES = new Set();

async function fetchOffers(user) {
  const response = await axios.post(
    API_URL,
    {
      tg_user_id: user.id,
      tg_login: user.username,
      lang: user.language_code,
      is_premium: user.is_premium,
    },
    {
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        Auth: AUTH_TOKEN,
      },
      httpsAgent,
    }
  );
  return response;
}

bot.onText(/\/tasks/, async (msg) => {
  const response = await fetchOffers(msg.from);
  const data = response.data;

  if (response.status === 200 && data.status === "not_ok") {
    const keyboard = data.offers.map((offer) => [{
      text: offer.type === "channel" ? "Подписаться" : "Перейти",
      url: offer.link,
    }]);
    keyboard.push([{ text: "Проверить ✅", callback_data: "check_tgrass" }]);

    await bot.sendMessage(msg.chat.id, "Выполнить задание", {
      reply_markup: { inline_keyboard: keyboard },
    });
  } else {
    await bot.sendMessage(msg.chat.id, "На данный момент нет доступных заданий");
  }
});

bot.on("callback_query", async (query) => {
  if (query.data !== "check_tgrass") return;
  await bot.answerCallbackQuery(query.id);

  const response = await fetchOffers(query.from);
  const data = response.data;

  if (response.status === 200 && data.status === "ok") {
    await bot.sendMessage(query.message.chat.id, "Задание успешно выполнено!");
    if (!ALREADY_CHECKED_MESSAGES.has(query.message.message_id)) {
      ALREADY_CHECKED_MESSAGES.add(query.message.message_id);
    }
  } else {
    await bot.sendMessage(query.message.chat.id, "Задание не выполнено!");
  }
});

Проверка подписки / задания

С помощью этого эндпоинта можно проверить выполнение отдельного задания пользователем.

POST https://tgrass.space/check

Данные в теле запроса

ПолеТипОписание
tg_user_idintИдентификатор пользователя
offer_idintИдентификатор оффера

Данные в ответе

ПолеТипОписание
status str subscribed — подписан
not_subscribed — не подписан
user_not_found — нет такого пользователя
offer_not_found — нет такого оффера
offer_expired — оффер не активен
is_fakeboolПризнак фейкового аккаунта

Пример запроса

curl -X POST https://tgrass.space/check \
-H "Content-Type: application/json" \
-H "Auth: YOUR_API_KEY" \
-d '{
  "tg_user_id": 123456789,
  "offer_id": 1054
}'

Пример на Python

import httpx

async def check_subs():
    async with httpx.AsyncClient(verify=False) as client:
        response = await client.post(
            "https://tgrass.space/check",
            json={"tg_user_id": 1111111, "offer_id": 1054},
            headers={
                "accept": "application/json",
                "Content-Type": "application/json",
                "Auth": "YOUR_API_KEY",
            },
        )
    return response.json()

Пример ответа

{
  "status": "subscribed",
  "is_fake": false
}

Документация для подключения фабрик ботов

Инструкция по API для владельцев фабрик ботов, которые хотят автоматизировать подключение к рекламной сети.

Авторизация: заголовок Auth: <BOT_MARKET_TOKEN>

Токен можно получить, обратившись в @tgrass_support_bot

1. Добавить нового бота — new_bot

POST https://tgrass.space/new_bot

При успешном создании возвращает API-ключ бота auth_token.

curl -X POST https://tgrass.space/new_bot \
-H "Content-Type: application/json" \
-H "Auth: BOT_MARKET_TOKEN" \
-d '{
  "username": "owner_login",
  "user_id": 123456789,
  "bot_name": "my_new_bot"
}'
{
  "auth_token": "ef3a1b2c..."
}

2. Баланс бота — balance

GET https://tgrass.space/balance

Заголовок Auth — API-ключ от бота (не путать с токеном для фабрик).

curl -X GET https://tgrass.space/balance \
-H "Auth: BOT_API_KEY"
{
  "balance": 1234.56
}

3. Статистика за дату — statistics

GET https://tgrass.space/statistics?date=YYYY-MM-DD

Заголовок Auth — API-ключ от бота. Возвращает подписки, отписки и доход за дату (UTC).

curl -X GET "https://tgrass.space/statistics?date=2026-01-01" \
-H "Auth: BOT_API_KEY"
{
  "date": "2026-01-01",
  "subs_count": 123,
  "unsubs_count": 5,
  "income": 234.50
}

Получение информации о пользователе по ID

Этот метод позволяет получить полную информацию о пользователе по его Telegram ID.

GET https://tgrass.space/subscriber/{subscriber_id}

В заголовок передаётся API-ключ Auth, полученный в сервисе @tgrassbot.

ПараметрТипОбязательныйОписание
subscriber_idint✅ID подписчика (Telegram user id)
curl -X GET "https://tgrass.space/subscriber/123456789" \
-H "Auth: YOUR_API_KEY"
{
  "id": 123456789,
  "tg_login": "username",
  "is_premium": false,
  "gender": "male",
  "lang": "ru",
  "city": "Москва",
  "country": "Россия",
  "age": "25-34"
}
ПолеТипОписание
idintID подписчика
tg_loginstr | nullUsername в Telegram
is_premiumbool | nullПризнак Telegram Premium
genderstr | nullПол (male / female)
langstr | nullЯзык пользователя
citystr | nullГород
countrystr | nullСтрана
agestr | nullВозрастной сегмент

Ошибки

КодКогда возникаетПример
401Не передан или неверный Auth{"detail":"Auth token not provided"}
404Подписчик не найден{"detail":"Subscriber not found"}

Webhooks

Где настроить

Настройки бота → Webhook ↩️

Два отдельных URL:

  • Webhook задания — при выполнении задания (подписке)
  • Webhook отписки — при отписке пользователя

Webhook задания

Когда: пользователь подписался на оффер через вашего бота.

Метод: POST, тело — JSON.

{
  "tg_user_id": 123456789,
  "offer_id": 42,
  "offer_link": "https://t.me/example",
  "timestamp": "2026-05-29T12:00:00+00:00"
}
ПолеОписание
tg_user_idTelegram ID пользователя
offer_idID оффера в Tgrass
offer_linkСсылка на канал/бот оффера
timestampВремя события (ISO 8601, UTC)

Webhook отписки

Когда: Tgrass обнаружил, что пользователь отписался от оффера.

Метод: POST, тело — JSON.

{
  "tg_user_id": 123456789,
  "offer_link": "https://t.me/example",
  "status": "unsubscribed",
  "reason": "unsubscribed"
}
ПолеОписание
tg_user_idTelegram ID пользователя
offer_linkСсылка на канал/бот оффера
statusСтатус события — unsubscribed
reasonПричина отписки — см. таблицу ниже
reasonОписание
unsubscribedПользователь отписался
wrong_langНекорректно передан язык пользователя
from_other_linkПодписка была с другой ссылки
fake_subscriberФейковый / заблокированный подписчик