Интеграция сервиса Tgrass для ботов MAX
Вы можете подключить сервис Tgrass для показа пользователю в мессенджере MAX обязательных офферов — каналов MAX, ботов или других ресурсов, на которые он должен подписаться или перейти перед продолжением использования вашего бота.
- 📡 Отправить HTTP-запрос для получения офферов и повторной проверки подписки
- 🔐 Авторизоваться с использованием API-ключа
- 🤖 Интегрировать логику в бота MAX (long polling / Platform API
platform-api.max.ru)
/max_offers и /max_check доступны только
для продавца типа MAX-бот в Tgrass.
Базовый URL API в примерах: https://tgrass.space
Интеграция с получением ссылок
При таком варианте интеграции бот сам запрашивает ссылки у Tgrass, отправляет сообщение пользователю в MAX (через Platform API) и при необходимости проверяет результат подписки.
Эндпоинт для интеграции
Для выдачи офферов и повторной проверки достаточно использовать один HTTP-эндпоинт — он отдаёт актуальный
список офферов для пользователя MAX и поле subscribed по каждому пункту.
https://tgrass.space/max_offers
Стандартный кейс
- Делаете
POST /max_offersи показываете пользователю ссылки (кнопкиlinkв inline-клавиатуре MAX) - Для проверки ещё раз вызываете
POST /max_offersс тем жеuser_id— по обновлённому ответу смотритеstatusиsubscribedу каждого оффера
Результат «всё выполнено» удобно смотреть по верхнему status в ответе:
ok— пользователь закрыл все требуемые офферыnot_ok— ещё есть невыполненные (смотритеsubscribed: false)no_offers— подходящих офферов сейчас нет
Проверка одного оффера
Для точечной проверки одного заказа используйте:
https://tgrass.space/max_check
В теле передаются user_id (MAX) и offer_id из ответа /max_offers
(поле offer_id у элемента списка offers).
Передаваемые данные (/max_offers)
В заголовок передаётся API-ключ Auth, полученный в сервисе
@tgrassbot (тот же ключ, что и для Telegram-интеграции продавца).
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
user_id | int | ✅ | Числовой ID пользователя в MAX (как в событиях API MAX: sender.user_id и т.п.) |
login | str | ❌ | Username / логин в MAX, если известен |
offers_limit | int | ❌ | Максимум офферов в ответе; имеет приоритет над лимитом в настройках бота |
Пример запроса через curl
curl -X POST https://tgrass.space/max_offers \
-H "Content-Type: application/json" \
-H "Auth: YOUR_API_KEY" \
-d '{
"user_id": 67764871,
"login": "username",
"offers_limit": 10
}'
Пример ответа
{
"status": "not_ok",
"offers": [
{
"name": "Канал в MAX",
"link": "https://max.ru/join/…",
"subscribed": false,
"type": "channel",
"channel_id": null,
"offer_id": 1012,
"price": 2.5
},
{
"name": null,
"link": "https://max.ru/id123_bot",
"subscribed": true,
"type": "bot",
"channel_id": null,
"offer_id": 1054,
"price": 1.2
}
],
"description": "…"
}
Данные в ответе
| Поле | Тип | Описание |
|---|---|---|
status |
str |
ok — пользователь закрыл все выданные офферыnot_ok — не всё выполненоno_offers — нет подходящих офферов
|
description | str | Текстовое описание статуса |
offers | list | Список офферов |
Объекты в offers[i]
| Поле | Тип | Описание |
|---|---|---|
name | str | null | Название оффера (может быть пустым) |
link | str | Ссылка на оффер (канал MAX, бот MAX, ресурс и т.д.) |
subscribed | bool | Подписан ли пользователь / выполнен ли оффер по данным Tgrass |
type |
str |
bot — ботchannel — канал / чатresource — внешний ресурс или ссылка
|
channel_id | str | null | Идентификатор канала |
offer_id | int | Идентификатор заказа в Tgrass |
price | float | Цена оффера |
Эндпоинт /max_check
Назначение: проверить один оффер для одного пользователя MAX.
https://tgrass.space/max_check
Тело запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
user_id | int | ✅ | ID пользователя в MAX (как в /max_offers) |
offer_id | int | ✅ | Значение offer_id из нужного элемента offers |
Пример curl
curl -X POST https://tgrass.space/max_check \
-H "Content-Type: application/json" \
-H "Auth: YOUR_API_KEY" \
-d '{
"user_id": 67764871,
"offer_id": 1012
}'
Пример ответа
{
"status": "subscribed"
}
Возможные значения status
| Значение | Смысл |
|---|---|
subscribed | Подписка / выполнение засчитаны |
not_subscribed | Ещё не выполнено |
user_not_found | Пользователь не найден |
offer_not_found | Оффер не найден |
offer_expired | Оффер недоступен (не активен и т.п.) |