Интеграция сервиса Tgrass для ботов MAX

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

Важно: эндпоинты /max_offers и /max_check доступны только для продавца типа MAX-бот в Tgrass.

Базовый URL API в примерах: https://tgrass.space

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

При таком варианте интеграции бот сам запрашивает ссылки у Tgrass, отправляет сообщение пользователю в MAX (через Platform API) и при необходимости проверяет результат подписки.

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

Для выдачи офферов и повторной проверки достаточно использовать один HTTP-эндпоинт — он отдаёт актуальный список офферов для пользователя MAX и поле subscribed по каждому пункту.

POST https://tgrass.space/max_offers

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

  1. Делаете POST /max_offers и показываете пользователю ссылки (кнопки link в inline-клавиатуре MAX)
  2. Для проверки ещё раз вызываете POST /max_offers с тем же user_id — по обновлённому ответу смотрите status и subscribed у каждого оффера

Результат «всё выполнено» удобно смотреть по верхнему status в ответе:

  • ok — пользователь закрыл все требуемые офферы
  • not_ok — ещё есть невыполненные (смотрите subscribed: false)
  • no_offers — подходящих офферов сейчас нет

Проверка одного оффера

Для точечной проверки одного заказа используйте:

POST https://tgrass.space/max_check

В теле передаются user_id (MAX) и offer_id из ответа /max_offers (поле offer_id у элемента списка offers).

Передаваемые данные (/max_offers)

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

ПолеТипОбязательноеОписание
user_idint✅Числовой ID пользователя в MAX (как в событиях API MAX: sender.user_id и т.п.)
loginstr❌Username / логин в MAX, если известен
offers_limitint❌Максимум офферов в ответе; имеет приоритет над лимитом в настройках бота

Пример запроса через 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 — нет подходящих офферов
descriptionstrТекстовое описание статуса
offerslistСписок офферов

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

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

Эндпоинт /max_check

Назначение: проверить один оффер для одного пользователя MAX.

POST https://tgrass.space/max_check

Тело запроса

ПолеТипОбязательноеОписание
user_idint✅ID пользователя в MAX (как в /max_offers)
offer_idint✅Значение 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Оффер недоступен (не активен и т.п.)