Получение данных пользователей

Возвращает постраничный список пользователей ресурса с расширенной информацией.

Запрос

Не забудьте добавить заголовок для авторизации запроса. Подробней в этом разделе

GET / POST /v1/get-users

Поддерживается GET и POST. При POST-запросе тело — JSON.

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

Параметр	Тип	По умолчанию	Описание
limit	int	20	Количество записей (макс. 500)
offset	int	0	Номер страницы (начиная с 0)

offset — это номер страницы, а не абсолютное смещение. Реальное смещение = offset × limit.

Фильтры

При GET передаются с префиксом filter_ (напр. filter_status=0). При POST передаются в объекте filters без префикса.

Фильтр	Тип	Описание
user_id	int	Telegram user ID
username	string	Частичное совпадение по username (без @)
search	string	Поиск по first_name, last_name, username
status	int	0 — активен, 1 — заблокировал/вышел
is_premium	int	0 — нет Premium, 1 — есть
gender	int	0 — не определён, 1 — мужской, 2 — женский

Примеры

GET:

GET /v1/get-users?limit=10&offset=0&filter_status=0&filter_is_premium=1

POST:

POST /v1/get-users
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "limit": 10,
  "offset": 0,
  "filters": {
    "status": 0,
    "is_premium": 1
  }
}

Ответ

{
  "ok": true,
  "data": {
    "count": 1234,
    "rows": [
      {
        "user_id": 123456789,
        "is_bot": false,
        "first_name": "Иван",
        "last_name": "Петров",
        "username": "ivanpetrov",
        "language_code": "ru",
        "is_premium": 1,
        "gender": 1,
        "time_zone": 3,
        "timezone_offset": 10800,
        "date_create": 1700000000,
        "date_last_active": 1716000000,
        "user_status": 0,
        "country": "Russia",
        "city": "Moscow",
        "verified": null,
        "scam": null,
        "fake": null,
        "bio": null,
        "stargifts_count": null,
        "tg_version": null,
        "personal_channel_id": null,
        "birth_day": null,
        "birth_month": null,
        "birth_year": null,
        "devices_name": null,
        "viewport_height": null,
        "geo": {
          "countryCode": "RU",
          "countryName": "Russia",
          "cityName": "Moscow",
          "latitude": 55.75,
          "longitude": 37.62
        },
        "utm": {
          "first": { "source": "telegram", "campaign": "promo2024" },
          "last": { "source": "direct" },
          "weight": {}
        },
        "addition_fields": {
          "phone": "+7999...",
          "custom_field": "value"
        },
        "connection_data": {}
      }
    ]
  }
}

Поля ответа

Поле	Тип	Описание
user_id	int	Telegram user ID
is_bot	bool|null	Является ли ботом
first_name	string|null	Имя
last_name	string|null	Фамилия
username	string|null	Username (без @)
language_code	string|null	Язык интерфейса Telegram (ru, en, ...)
is_premium	int|null	Telegram Premium: 1 — есть, 0 — нет
gender	int|null	Пол: 0 — не определён, 1 — мужской, 2 — женский
time_zone	float|null	Смещение UTC в часах (напр. 3 для UTC+3)
timezone_offset	int|null	Смещение UTC в секундах
date_create	int|null	Unix timestamp первого взаимодействия с ботом
date_last_active	int|null	Unix timestamp последней активности
user_status	int|null	Статус: 0 — активен, 1 — заблокировал/вышел
country	string|null	Страна (из geo, определена по IP)
city	string|null	Город (из geo, определён по IP)
verified	bool|null	Флаг верификации Telegram
scam	bool|null	Флаг scam-аккаунта
fake	bool|null	Флаг fake-аккаунта
bio	string|null	Биография из профиля Telegram
stargifts_count	int|null	Количество Star Gifts
tg_version	string|null	Версия Telegram клиента
personal_channel_id	int|null	ID личного канала (если установлен)
birth_day	int|null	День рождения
birth_month	int|null	Месяц рождения
birth_year	int|null	Год рождения
devices_name	string|null	Название устройства
viewport_height	int|null	Высота Mini App viewport в пикселях
geo	object	Полный объект геолокации (IP-based)
utm	object	UTM-параметры: first, last, weight
addition_fields	object	Кастомные поля, добавленные через бот
connection_data	object	Метаданные соединения

Все скалярные поля всегда присутствуют в ответе. Если данных нет — значение null. Объекты (geo, utm, addition_fields, connection_data) при отсутствии данных возвращаются как {}.

---

Объект geo

Геолокация пользователя, если была определенна.

"geo": {
  "ip": "98.116.0.1",
  "countryCode": "US",
  "countryName": "United States",
  "regionName": "New York",
  "region": "NY",
  "cityName": "New York",
  "timezone": "America/New_York",
  "timezone_offset": -14400,
  "lat": 40.7128,
  "lon": -74.0060,
  "zip": "10001"
}

Поле	Тип	Описание
ip	string|null	IP-адрес пользователя
countryCode	string|null	Код страны ISO 3166-1 alpha-2 (напр. RU, US)
countryName	string|null	Название страны
regionName	string|null	Полное название региона / области
region	string|null	Краткий код региона
cityName	string|null	Название города
timezone	string|null	IANA timezone (напр. America/New_York)
timezone_offset	int|null	Смещение UTC в секундах (напр. 10800 для UTC+1)
lat	float|null	Широта
lon	float|null	Долгота
zip	string|null	Почтовый индекс

Поля countryName и cityName также дублируются в корне объекта пользователя для удобства.

---

Объект utm

"utm": {
  "first": {
    "source": "telegram",
    "campaign": "promo2024",
    "none": "raw_start_value"
  },
  "last": {
    "source": "google",
    "medium": "cpc"
  },
  "weight": {
    "source": "telegram"
  },
  "referral_id": 987654321,
  "invite_link_id": 42
}

Поле	Тип	Описание
first	object	UTM-параметры первого перехода пользователя
last	object	UTM-параметры последнего перехода
weight	object	UTM-параметры последнего значимого перехода
referral_id	int|null	Telegram user ID пользователя, который пригласил (реферал)
invite_link_id	int|null	ID инвайт-ссылки, по которой пришёл пользователь

Ключи внутри first / last / weight — это названия UTM-параметров, настроенных в боте (например source, medium, campaign, content, term).

---

Объект addition_fields

Произвольные кастомные поля, которые бот записывает для конкретного пользователя — например, через действия автоматизации «Записать поле» или через API send-user-field. Набор ключей и типы значений полностью определяются логикой вашего бота.

"addition_fields": {
  "phone": "[phone]",
  "email": "[e-mail]",
  "score": 42,
  "subscribed": true,
  "referral_code": "ABC123"
}

Значением может быть строка, число, булево или null. Если для пользователя кастомных полей нет — возвращается {}.

---

Объект connection_data

Данные из связанных ботов (Connected Resources). Если ваш бот настроен на получение данных от другого бота (например, пользователь уже взаимодействовал с основным ботом, а здесь используется дочерний), этот объект будет содержать UTM и кастомные поля из связанного бота.

Ключи объекта — строковые идентификаторы связанных ресурсов (resource_key). Каждый вложенный объект может содержать:

"connection_data": {
  "main_bot": {
    "utm": {
      "first": { "source": "telegram" },
      "last": { "source": "telegram" },
      "weight": {}
    },
    "addition_fields": {
      "phone": "[phone]"
    }
  }
}

Поле	Описание
utm	UTM-данные пользователя из связанного бота (если включена передача UTM)
addition_fields	Кастомные поля из связанного бота (если включена передача параметров)

Если связанных ботов нет или передача данных не настроена — возвращается {}.

Коды ошибок

Код	Описание
401	API-ключ не передан или недействителен
403	Метод недоступен на вашем тарифе (требуется Premium)
500	Внутренняя ошибка сервера

Пример ошибки:

{
  "ok": false,
  "error": { "errors": "Premium tariff required" },
  "error_code": 403
}