API сервиса и примеры
Вы можете подключить сервис Tgrass для показа пользователю обязательных офферов — каналов, ботов или других ресурсов, на которые он должен подписаться или перейти перед продолжением использования вашего бота.
- 📡 Отправить HTTP-запрос для получения офферов и проверки подписки
- 🔐 Авторизоваться с использованием API-ключа
- 🤖 Интегрировать логику в Telegram-бота
Интеграция с получением ссылок
При таком варианте интеграции боты сами запрашивают ссылки, отправляют сообщение пользователю и проверяют результат подписки. Рекомендован для тех, кто не передаёт токен от бота.
Эндпоинт для интеграции
Для интеграции офферов достаточно использовать один HTTP-эндпоинт: он отдаёт новые офферы для пользователя и одновременно проверяет подписку.
https://tgrass.space/offers
Если у вас в боте задания, используйте эндпоинт
https://tgrass.space/tasks
Стандартный кейс
- Делаем запрос и возвращаем офферы пользователю
- Для проверки делаем ещё один запрос на тот же эндпоинт
/offersили/tasksи проверяем подписку. Результат определяется по статусу в ответе (ok,not_ok,no_offers)
Для проверки отдельного оффера можно использовать метод https://tgrass.space/check.
Передаваемые данные
В заголовок передаётся API-ключ Auth, полученный в сервисе @tgrassbot.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
tg_user_id | int | ✅ | Telegram ID пользователя |
is_premium | bool | ✅ | Является ли пользователь подписчиком Telegram Premium |
lang | str | ✅ | Языковой код пользователя в Telegram, например en, ru, uk |
tg_login | str | ❌ | Username пользователя |
gender | str | ❌ | Пол пользователя — male или female |
exclude_channels | list[str] | ❌ | Список идентификаторов каналов, которые нужно исключить |
offers_limit | int | ❌ | Количество спонсоров в ответе. Имеет приоритет над настройкой в боте |
Пример запроса через 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 — нет подходящих офферов
|
description | str | Текстовое описание статуса |
offers | list | Список офферов |
Объекты в offers[i]
| Поле | Тип | Описание |
|---|---|---|
name | str | null | Название оффера (может быть пустым) |
link | str | Ссылка на оффер (бот, канал или внешний ресурс) |
subscribed | bool | Подписан ли пользователь на этот оффер |
type |
str |
bot — Telegram-ботchannel — Telegram-каналresource — внешний ресурс или ссылкаfolder — папка
|
channel_id | str | null | Идентификатор канала |
offer_id | int | Уникальный идентификатор оффера |
price | float | Цена оффера |
Сброс времени обновления спонсоров
Если после выполнения задания нужно сразу получить новые офферы при запросе /offers
и не ждать настраиваемое время обновления, используйте метод сброса:
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, "Задание не выполнено!");
}
});
Проверка подписки / задания
С помощью этого эндпоинта можно проверить выполнение отдельного задания пользователем.
https://tgrass.space/check
Данные в теле запроса
| Поле | Тип | Описание |
|---|---|---|
tg_user_id | int | Идентификатор пользователя |
offer_id | int | Идентификатор оффера |
Данные в ответе
| Поле | Тип | Описание |
|---|---|---|
status |
str |
subscribed — подписанnot_subscribed — не подписанuser_not_found — нет такого пользователяoffer_not_found — нет такого оффераoffer_expired — оффер не активен
|
is_fake | bool | Признак фейкового аккаунта |
Пример запроса
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.
https://tgrass.space/subscriber/{subscriber_id}
В заголовок передаётся API-ключ Auth, полученный в сервисе @tgrassbot.
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
subscriber_id | int | ✅ | 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"
}
| Поле | Тип | Описание |
|---|---|---|
id | int | ID подписчика |
tg_login | str | null | Username в Telegram |
is_premium | bool | null | Признак Telegram Premium |
gender | str | null | Пол (male / female) |
lang | str | null | Язык пользователя |
city | str | null | Город |
country | str | null | Страна |
age | str | 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_id | Telegram ID пользователя |
offer_id | ID оффера в 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_id | Telegram ID пользователя |
offer_link | Ссылка на канал/бот оффера |
status | Статус события — unsubscribed |
reason | Причина отписки — см. таблицу ниже |
| reason | Описание |
|---|---|
unsubscribed | Пользователь отписался |
wrong_lang | Некорректно передан язык пользователя |
from_other_link | Подписка была с другой ссылки |
fake_subscriber | Фейковый / заблокированный подписчик |