Zapnoty — Подписчики и теги

Подписчики

Управление списком подписчиков и их тегами.

GET /v1/subscribers

Список подписчиков проекта. Пагинация через query-параметры.

limit number

Кол-во записей (по умолчанию 50, макс. 200)

offset number

Смещение от начала списка (по умолчанию 0)

channel string

Фильтр по каналу: telegram или max

Ответ

{

"subscribers": [

{

"id": "550e8400-e29b-41d4-a716-446655440000",

"channel": "telegram",

"first_name": "John",

"username": "johndoe",

"lang": "ru",

"permissions": ["orders"],

"tags": ["vip"],

"active": true,

"blocked": false,

"created_at": "2026-03-05T12:00:00Z",

"last_seen_at": "2026-03-06T09:30:00Z",

"external_id": "user-42"

}

"total": 150

}

username хранится и возвращается без префикса @ (например johndoe, не @johndoe). Пустая строка — если username у пользователя не задан.

lang — двухбуквенный код языка по ISO 639-1 (ru, en). Определяется из языка интерфейса мессенджера при подписке.

PUT /v1/subscribers/:id/tags

Обновление тегов подписчика. Передайте полный массив тегов. Теги должны быть предварительно созданы в настройках проекта или через API. Несуществующие теги будут автоматически созданы (если не достигнут лимит 20).

PUT /v1/subscribers/550e8400-e29b-41d4-a716-446655440000/tags

{

"tags": ["vip", "beta"]

}

Ответ

{

"updated": true

}

GET /v1/subscribe-link

Постоянная deeplink-ссылка простой подписки на проект для Telegram и Max. Опциональные query-параметры permission и tag добавляются в payload — подписчик при переходе по ссылке сразу получает выбранное разрешение и/или тег. telegram_link или max_link равны null, если соответствующий бот не сконфигурирован.

permission string

Ключ разрешения, выдаётся подписчику при переходе (латиница, цифры, дефис; 1-64 символа). Должен существовать в проекте, иначе 400.

tag string

Тег, присваивается подписчику при переходе (латиница, цифры, дефис; 1-64 символа). Должен существовать в проекте, иначе 400.

GET /v1/subscribe-link?permission=orders&tag=vip

Ответ

{

"telegram_link": "https://t.me/zapnoty_bot?start=proj_my-app_perm_orders_tag_vip",

"max_link": "https://max.ru/zapnoty_bot?start=proj_my-app_perm_orders_tag_vip"

}

Как узнать доступные значения

permission и tag должны быть заранее заведены в проекте — иначе эндпоинт вернёт 400. Чтобы получить список доступных значений, сначала вызовите GET /v1/permissions и GET /v1/tags, затем подставьте нужные ключи в GET /v1/subscribe-link.

# 1. узнать доступные разрешения и теги

GET /v1/permissions

GET /v1/tags

# 2. сгенерировать ссылку с существующими значениями

GET /v1/subscribe-link?permission=orders&tag=vip