project-users

Эндпоинтов: 13

`DELETE` /api/projects/{id}/users

Удалить всех пользователей и сообщения проекта

Авторизация: Cookie (connect.sid) или Bearer PAT

Wipe: DELETE из bot_users и bot_messages по project_id (и token_id, если задан). deletedCount — сумма rowCount обеих таблиц.

UI: очистка базы (use-delete-all-users). Не путать с DELETE …/users/{userId}.

curl -s -X DELETE 'http://localhost:5000/api/projects/42/users?tokenId=7' -b cookies.txt

Operation ID: delete_api_projects_id_users_f63ac5e2fbfb0a15

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Данные очищены
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка удаления

Пример ответа `200`

{
  "message": "All user data deleted successfully",
  "deleted": true,
  "deletedCount": 250
}

`GET` /api/projects/{id}/users

Список пользователей и диалогов проекта

Авторизация: Cookie (connect.sid) или Bearer PAT

Вкладки «Диалоги» / «Пользователи». С limit — { users, total, hasMore }; без limit — плоский массив. dialogKind фильтрует личные/группы/каналы.

Auth: cookie / Bearer PAT (requireApiAuth) + проверка доступа к проекту.

Клиент: список диалогов, use-system-tables (таблица «Пользователи»).

curl -s 'http://localhost:5000/api/projects/42/users?limit=50&tokenId=7' -b cookies.txt

Operation ID: get_api_projects_id_users_4f1fc875c745ed89

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Скоуп по token_id бота. Без параметра — все токены проекта.	`"7"`
`limit`	query	нет	Размер страницы; без параметра — legacy-массив без пагинации	`"50"`
`offset`	query	нет	Смещение страницы (нужен limit)	`"0"`
`search`	query	нет	Поиск по имени, username, user_id или тексту сообщений	`"иван"`
`filterActive`	query	нет	Фильтр активности: true	false
`sortBy`	query	нет	Поле сортировки (whitelist на сервере)	`"lastInteraction"`
`sortDir`	query	нет	Направление сортировки	`"desc"`
`dialogKind`	query	нет	Фильтр типа диалога (приоритетнее includeGroups)	`"all"`
`includeGroups`	query	нет	Legacy-флаг групп (предпочтительнее dialogKind)	`"true"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Пагинированный список или массив
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту

Пример ответа `200`

{
  "users": [
    {
      "id": 1,
      "userId": "123456789",
      "userName": "ivan",
      "firstName": "Иван",
      "lastName": "Петров",
      "isActive": true,
      "isGroup": false,
      "interactionCount": 12,
      "lastInteraction": "2026-08-10T12:00:00.000Z"
    }
  ],
  "total": 120,
  "hasMore": true
}

`GET` /api/projects/{id}/users/activity

Активные пользователи по времени

Авторизация: Cookie (connect.sid) или Bearer PAT

Считает уникальных людей, что-то сделавших за каждый слот (входящее сообщение или нажатие inline-кнопки, message_type=user). Ответы бота не учитываются.

С granularity (1m|5m|1h|1w|1d|7d|30d):

короткие окна (1m/5m/1h) — из bot_messages;
длинные (1w/1d/7d/30d) — из user_activity_daily (переживают очистку сообщений и удаление людей).

Поле newcomers — люди, у которых время первого появления попадает в тот же слот; returning = total − newcomers.

activeInWindow / newInWindow — уникальные за всё окно (сумма точек не равна итогу: один человек за три дня — один, не три).

Клиент: use-users-activity.

curl -s 'http://localhost:5000/api/projects/42/users/activity?granularity=1d&tokenId=7' \
  -b cookies.txt

Operation ID: get_api_projects_id_users_activity_b57644b2f7aebb54

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`granularity`	query	нет	Окно и шаг: 1m	5m
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Точки слотов и итоги окна
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка БД

Пример ответа `200`

{
  "points": [
    {
      "date": "2026-09-01T00:00:00.000Z",
      "total": 42,
      "newcomers": 7,
      "returning": 35
    },
    {
      "date": "2026-09-02T00:00:00.000Z",
      "total": 38,
      "newcomers": 4,
      "returning": 34
    }
  ],
  "activeInWindow": 310,
  "newInWindow": 58
}

`GET` /api/projects/{id}/users/growth

Прирост пользователей по времени

Авторизация: Cookie (connect.sid) или Bearer PAT

С granularity (1m|5m|1h|1w|1d|7d|30d) — ряд слотов generate_series, date в ISO. Без него — legacy period (7d|30d|90d, default 30d), date как YYYY-MM-DD; пустой результат — fallback на 90 дней.

Клиент: use-growth (всегда шлёт granularity).

curl -s 'http://localhost:5000/api/projects/42/users/growth?granularity=1d&tokenId=7' \
  -b cookies.txt

Operation ID: get_api_projects_id_users_growth_992c479a0fd064c3

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`granularity`	query	нет	1m	5m
`period`	query	нет	Обратная совместимость; игнорируется при granularity	`"30d"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Массив [{ date, count }]
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка БД

Пример ответа `200`

[
  {
    "date": "2026-08-01T00:00:00.000Z",
    "count": 5
  },
  {
    "date": "2026-08-02T00:00:00.000Z",
    "count": 3
  }
]

`GET` /api/projects/{id}/users/growth-by-source

Прирост пользователей по источникам

Авторизация: Cookie (connect.sid) или Bearer PAT

granularity обязателен (иначе 400). Ключи sources — COALESCE(deep_link_param,'direct'). Для 5m — особый truncate минут.

Клиент: use-growth-by-source.

curl -s 'http://localhost:5000/api/projects/42/users/growth-by-source?granularity=1d&tokenId=7' \
  -b cookies.txt

Operation ID: get_api_projects_id_users_growth_by_source_4c188a374c001e66

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`granularity`	query	да	Обязательный: 1m	5m
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Массив [{ date, sources }]
400	Нет granularity
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка БД

Пример ответа `200`

[
  {
    "date": "2026-08-01T00:00:00.000Z",
    "sources": {
      "direct": 3,
      "instagram": 2
    }
  },
  {
    "date": "2026-08-02T00:00:00.000Z",
    "sources": {
      "direct": 1
    }
  }
]

`GET` /api/projects/{id}/users/popular-buttons

Топ-10 популярных inline-кнопок

Авторизация: Cookie (connect.sid) или Bearer PAT

Нажатия из bot_messages (message_type=user, message_data.button_clicked=true). Label — button_text или callback_data. Окно по granularity (default как 1d → 30 days).

Клиент: use-popular-buttons.

curl -s 'http://localhost:5000/api/projects/42/users/popular-buttons?granularity=1d&tokenId=7' \
  -b cookies.txt

Operation ID: get_api_projects_id_users_popular_buttons_a34efe1da5f1ae39

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`granularity`	query	нет	1m	5m
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	До 10 элементов [{ label, count }]
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка БД

Пример ответа `200`

[
  {
    "label": "Купить",
    "count": 42
  },
  {
    "label": "Помощь",
    "count": 18
  }
]

`GET` /api/projects/{id}/users/stats

Агрегированная статистика пользователей

Авторизация: Cookie (connect.sid) или Bearer PAT

Счётчики из bot_users + totalInteractions из bot_messages (COUNT входящих и исходящих). Опциональный tokenId.

Auth: cookie / Bearer PAT; при известном owner — hasProjectAccess.

Клиент: use-stats, карточки дашборда базы пользователей.

curl -s 'http://localhost:5000/api/projects/42/users/stats?tokenId=7' -b cookies.txt

Operation ID: get_api_projects_id_users_stats_080bdbbdda634b0b

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Агрегаты; среднее на пользователя может быть дробным
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка БД

Пример ответа `200`

{
  "totalUsers": 150,
  "activeUsers": 120,
  "blockedUsers": 30,
  "blockedBotUsers": 8,
  "deletedUsers": 3,
  "premiumUsers": 12,
  "usersWithResponses": 45,
  "totalInteractions": 3200,
  "avgInteractionsPerUser": 21,
  "uniqueLanguages": 5,
  "deepLinkUsers": 40,
  "referralUsers": 18,
  "privateUsers": 80,
  "groupUsers": 24,
  "channelUsers": 5,
  "usersInSeveralPlaces": 3
}

`GET` /api/projects/{id}/users/traffic

Источники трафика и языки пользователей

Авторизация: Cookie (connect.sid) или Bearer PAT

sources — группировка по COALESCE(deep_link_param,'direct') с %. languages — топ-20 language_code (NULL исключены) с %.

Клиент: use-traffic (нормализует count/percentage в number).

curl -s 'http://localhost:5000/api/projects/42/users/traffic?tokenId=7' -b cookies.txt

Operation ID: get_api_projects_id_users_traffic_75eeead714655ccb

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	sources + languages
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
500	Ошибка БД

Пример ответа `200`

{
  "sources": [
    {
      "param": "direct",
      "count": 80,
      "percentage": 53.3
    },
    {
      "param": "instagram",
      "count": 40,
      "percentage": 26.7
    }
  ],
  "languages": [
    {
      "code": "ru",
      "count": 100,
      "percentage": 66.7
    },
    {
      "code": "en",
      "count": 50,
      "percentage": 33.3
    }
  ]
}

`GET` /api/projects/{id}/users/variables

Переменные user_data как таблица

Авторизация: Cookie (connect.sid) или Bearer PAT

Пользователи с непустым user_data. columns = user_id, username + ключи user_data (без _/waiting_/input_). Значения — строки.

Auth: cookie / Bearer PAT + requireProjectAccess.

Клиент: use-system-tables (таблица «Переменные»).

curl -s 'http://localhost:5000/api/projects/42/users/variables?limit=200&tokenId=7' \
  -b cookies.txt

Operation ID: get_api_projects_id_users_variables_af4b67f8f324a301

Параметры

Имя	In	Обязательный	Описание	Пример
`id`	path	да	Числовой ID проекта	`"42"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`limit`	query	нет	Максимум пользователей с непустым user_data	`"200"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	{ columns, rows }
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту (requireProjectAccess)
500	Ошибка БД

Пример ответа `200`

{
  "columns": [
    "user_id",
    "username",
    "city",
    "age"
  ],
  "rows": [
    {
      "user_id": "123",
      "username": "ivan",
      "city": "Москва",
      "age": "25"
    }
  ]
}

`DELETE` /api/projects/{projectId}/users/{userId}

Удалить одного пользователя и его сообщения

Авторизация: Cookie (connect.sid) или Bearer PAT

UI: удаление пользователя в редакторе.

Удаляет bot_messages и строку bot_users для (user_id, project_id, token_id).

Не путать с DELETE /api/projects/{id}/users — wipe всех пользователей.

curl -s -X DELETE 'http://localhost:5000/api/projects/42/users/123456789?tokenId=7' \
  -b cookies.txt

Operation ID: delete_api_projects_projectId_users_userId_5b1cd8490f418d2f

Параметры

Имя	In	Обязательный	Описание	Пример
`projectId`	path	да	ID проекта	`"42"`
`userId`	path	да	Telegram user_id	`"123456789"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Успешное удаление
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
404	Пользователь не найден
503	Сервис не настроен (setupGuard)

Пример ответа `200`

{
  "message": "User data deleted successfully"
}

`GET` /api/projects/{projectId}/users/{userId}

Прочитать пользователя и сохранённые ответы выбранного бота

Авторизация: Cookie (connect.sid) или Bearer PAT

Operation ID: get_api_projects_projectId_users_userId_7e5da89f9203cbfd

Параметры

Имя	In	Обязательный	Описание	Пример
`projectId`	path	да	—	—
`userId`	path	да	—	—
`tokenId`	query	нет	—	—

Ответы

Код	Описание
200	Пользователь с JSON userData
400	Некорректные параметры
401	Нет авторизации
403	Нет доступа к проекту
404	Бот или пользователь не найдены
500	Не удалось прочитать данные

`PUT` /api/projects/{projectId}/users/{userId}

Обновить статус активности пользователя

Авторизация: Cookie (connect.sid) или Bearer PAT

UI: активен / неактивен в базе пользователей.

Обновляет is_active и last_interaction. tokenId — в query. Токен через resolveEffectiveProjectTokenId.

curl -s -X PUT 'http://localhost:5000/api/projects/42/users/123456789?tokenId=7' \
  -b cookies.txt -H 'Content-Type: application/json' -d '{"isActive":1}'

Operation ID: put_api_projects_projectId_users_userId_c43f2cc46c603623

Тело запроса: UpdateBotUserRequest

Параметры

Имя	In	Обязательный	Описание	Пример
`projectId`	path	да	ID проекта	`"42"`
`userId`	path	да	Telegram user_id	`"123456789"`
`tokenId`	query	нет	Опциональный ID токена бота. Без него — все токены проекта.	`"7"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Пример тела запроса

{
  "isActive": 1
}

Ответы

Код	Описание
200	Обновлённая строка bot_users
400	Нет полей для обновления
401	Нет session cookie и Bearer PAT
403	Нет доступа к проекту
404	Пользователь не найден
503	Сервис не настроен (setupGuard)

Пример ответа `200`

{
  "user_id": "123456789",
  "project_id": 42,
  "token_id": 7,
  "username": "ivan",
  "first_name": "Иван",
  "is_active": 1
}

`GET` /api/projects/{projectId}/users/unavailable

Удалённые и заблокировавшие бота

Авторизация: Cookie (connect.sid) или Bearer PAT

Люди выбранного бота с is_deleted или is_blocked. Telegram не вызывается, текст сообщений не возвращается.

Operation ID: get_api_projects_projectId_users_unavailable_d17cb702b19d6c95

Параметры

Имя	In	Обязательный	Описание	Пример
`projectId`	path	да	ID проекта	`"12"`
`tokenId`	query	да	ID бота	`"10"`
`kind`	query	нет	—	`"both"`
`limit`	query	нет	—	`"20"`
`offset`	query	нет	—	`"0"`
`Authorization`	header	нет	Authorization: Bearer mcp_… — PAT агента (альтернатива cookie)	`"Bearer mcp_xxxxxxxx"`
`connect.sid`	cookie	нет	Session cookie после login. Не нужна при Authorization: Bearer mcp_…	`"s%3Axxxx.yyyy"`

Ответы

Код	Описание
200	Страница людей
400	Нет бота или неверная страница
401	Нет авторизации
403	Нет доступа к проекту
404	Бот не принадлежит проекту

DELETE /api/projects/{id}/users​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/activity​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/growth​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/growth-by-source​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/popular-buttons​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/stats​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/traffic​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{id}/users/variables​

Параметры​

Ответы​

Пример ответа 200​

DELETE /api/projects/{projectId}/users/{userId}​

Параметры​

Ответы​

Пример ответа 200​

GET /api/projects/{projectId}/users/{userId}​

Параметры​

Ответы​

PUT /api/projects/{projectId}/users/{userId}​

Параметры​

Пример тела запроса​

Ответы​

Пример ответа 200​

GET /api/projects/{projectId}/users/unavailable​

Параметры​

Ответы​

`DELETE` /api/projects/{id}/users

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/activity

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/growth

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/growth-by-source

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/popular-buttons

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/stats

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/traffic

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{id}/users/variables

Параметры

Ответы

Пример ответа `200`

`DELETE` /api/projects/{projectId}/users/{userId}

Параметры

Ответы

Пример ответа `200`

`GET` /api/projects/{projectId}/users/{userId}

Параметры

Ответы

`PUT` /api/projects/{projectId}/users/{userId}

Параметры

Пример тела запроса

Ответы

Пример ответа `200`

`GET` /api/projects/{projectId}/users/unavailable

Параметры

Ответы