# GNR Bot — настройка чатов, модулей и интеграций

> Справочник для владельцев чатов и AI-ассистентов. GNR Bot работает с VK, Telegram и Discord. Здесь описаны публичный API v1, настройки панели и проверка результата. Наличие функции в справочнике не означает, что она включена в конкретном чате.

Сайт: https://gnrbot.ru
API: https://api.gnrbot.ru/api/v1
Документация в панели: https://gnrbot.ru/dashboard/api

## Быстрый старт и выбор чата

1. Откройте панель, выберите нужный чат и создайте ключ в разделе API. Выдайте только нужные scopes и права read / write / readwrite.
2. Выполните GET /api/v1/capabilities. Сверьте chat_id, plan.plan_key, plan.api_daily_limit и scopes.
3. Прочитайте текущее состояние нужного раздела через GET. Сохраните изменяемые значения для возврата.
4. Выполните один запрос изменения. Проверьте HTTP-статус и ответ, затем перечитайте состояние через GET.
5. Проверьте команду в реальном чате или интеграцию в панели. Успешное сохранение не доказывает доступность внешнего сервиса или доставку сообщения.

## Авторизация и права

Передавайте X-API-Key: gnr_<32 hex>. Отдельный API-сервис также принимает Authorization: Bearer gnr_...; для совместимости используйте X-API-Key. Для запросов с JSON-телом (POST/PUT/PATCH/DELETE) задавайте Content-Type: application/json. Ключ храните на своей серверной стороне или в переменной окружения, не в опубликованном JS, URL или тексте команды.
Ключ привязан к одному внутреннему UUID чата. chat_id из capabilities — не числовой ID беседы VK, Telegram или Discord. Для другого чата нужен его ключ. В публичных запросах chatId обычно не передаётся; там, где поле принимается, оно должно совпасть с чатом ключа.
Права read / write / readwrite и разрешённые IP проверяются для каждого запроса. capabilities.endpoints фильтруется по scopes и не подтверждает право записи: ключ с read может видеть описание PATCH и получить 403 при его вызове.
Исключение: GET /api/v1/usage и GET /api/v1/usage/history сейчас требуют сессию пользователя панели и query chatId, одного API-ключа недостаточно. Историю расхода смотрите в панели.

## Подписки и экономный расход API

API доступен и на Free. Суточные лимиты: free — 75, starter — 200, pro — 350, configurator_plus — 500, maximum — 1000. Актуальный лимит возвращает capabilities.plan.api_daily_limit.
Авторизованное чтение capabilities тоже расходует квоту; запрос может расходовать её даже при последующей ошибке в теле. Кэшируйте чтение на своей стороне и обновляйте по действию пользователя. Не опрашивайте все разделы каждую секунду. Задавайте небольшой limit, обходите страницы последовательно и прекращайте загрузку после конца списка.
Для интеграций ориентируйтесь на providers[].minPlan и locked в GET /api/v1/integrations: администратор может менять требования и видимость. Скрытая карточка не означает остановку сохранённого подключения. Полный экспорт настроек бота доступен на Maximum через панель; публичные списки не являются резервной копией всех настроек.

## Capabilities

Сначала вызовите `GET /api/v1/capabilities`. Ответ показывает chat_id, тариф, scopes, эндпоинты, имена команд и RCON-серверы (id и имя, без паролей). capabilities.modules — разрешённые разделы ключа, например commands или settings; игровые модули clans, economy и другие смотрите отдельно в GET /api/v1/modules.
capabilities.commands содержит максимум 80 записей, formats — максимум 40, rcon_servers — максимум 40. Это краткая сводка, не полный экспорт и не полный список поддерживаемых шаблонов. Команды читайте страницами в /commands, сохранённые форматы — в /formats. Ответы не содержат паролей и кэша автокнопок.

## Полная настройка RCON через API

GET /api/v1/rcon возвращает id, rcon_server_id, command_name (и совместимое command), rcon_template, params_schema, required_rank, cooldown, response_template, response_rules, is_enabled, show_in_list. Пароли серверов не выдаются.
POST /rcon создаёт команду (201 с data.id); обязательны rcon_server_id, command_name, rcon_template. PUT /rcon требует id и изменяемые поля: пропущенные значения сохраняются. DELETE /rcon принимает JSON {id}. PATCH по имени остаётся переключателем enabled. Все методы привязаны к чату ключа и scope commands; создание/изменение не выполняет RCON на сервере.
Параметры params_schema задаются массивом {name,label,required}; в RCON-шаблоне используются позиционные {1}, {2}, …, {10}, а не имена параметров. Шаблон ответа поддерживает {response}, {lines}, {line_count}. Не путайте его с полем vorker кастомной команды.
GET /auto-buttons теперь возвращает все настройки разбора и source_rcon_command_id, source_rcon_server_id, cache_ttl. В PUT опущенные поля сохраняются. Кэш результатов в ответ не включается.

### Статистика сервера и кнопка смены карты

Нужны scopes commands, settings и ranks. Сначала получите реальные ID: capabilities.rcon_servers и GET /ranks. Замените rcon_server_id, required_rank и адрес play.example.com. Нажатие кнопки запускает обычную RCON-команду с проверкой ранга на стороне бота.

1. GET /api/v1/capabilities
Найдите RCON-сервер этого чата. Его пароль хранится в интеграции и в запрос не передаётся.

2. GET /api/v1/ranks
Выберите ранг администратора для команды смены карты. 1 ниже — пример ID, не универсальный ранг.

3. POST /api/v1/rcon
Создайте действие кнопки. Это только сохранение настройки; карта при HTTP-запросе не меняется.
```json
{
  "rcon_server_id": 1,
  "command_name": "сменить",
  "rcon_template": "changelevel {1}",
  "required_rank": 1,
  "cooldown": 15,
  "params_schema": [
    {
      "name": "map",
      "label": "Карта",
      "required": true
    }
  ],
  "response_template": "Ответ сервера:\n{response}"
}
```

4. POST /api/v1/commands
Команда «сервер» объединяет текущие данные, историю онлайна и кнопку. Для истории сервер должен быть добавлен в мониторинг чата.
```json
{
  "com": "сервер",
  "vorker": "|server|\n|stats;text|\nВыберите действие:",
  "description": "Сводка и управление картой",
  "cooldown": 10,
  "custom": {
    "ip": "play.example.com:27015",
    "game_type": "cs16",
    "response_format": "auto",
    "notify_mentions": 0
  },
  "buttons": [
    {
      "label": "Сменить на Dust2",
      "action": "command",
      "value": "сменить de_dust2",
      "color": "primary",
      "row": 0
    }
  ],
  "button_response_mode": "new",
  "status": 1,
  "show_in_list": 1
}
```

5. PATCH /api/v1/formats
Настройте строку онлайна для |server|. Другие ключи и образцы доступны в GET /formats → defaults.
```json
{
  "command_type": "server_info",
  "format_key": "online",
  "format_value": "Игроки: {players} из {maxplayers}",
  "is_enabled": true
}
```

6. GET /api/v1/commands?command=сервер
Ответ data — полная конфигурация. Для изменения скопируйте её в PUT /commands и поменяйте нужное поле, сохранив остальные.

### Кнопки из списка карт RCON

Сначала создайте RCON-команду «сменить» из предыдущего примера. Список maps * зависит от сервера; проверьте regex на его фактическом ответе. Автокнопки появятся в ответе команды «карты».

1. POST /api/v1/rcon
Сохраните возвращённый data.id: это ID команды-источника для следующего шага.
```json
{
  "rcon_server_id": 1,
  "command_name": "карты",
  "rcon_template": "maps *",
  "required_rank": 1,
  "cooldown": 10,
  "response_template": "Выберите карту:\n{response}"
}
```

2. POST /api/v1/auto-buttons
Замените source_rcon_command_id на data.id предыдущего шага. Кэш уменьшает число обращений к игровому серверу.
```json
{
  "name": "Выбор карты",
  "source_rcon_command_id": 1,
  "source_command": "maps *",
  "ensure_source": false,
  "ensure_target": false,
  "parse_mode": "simple",
  "line_regex": "(?:^|\\s)((?:de|cs|as|aim|awp|fy)_[a-zA-Z0-9_-]+)(?:\\.bsp)?(?=\\s|$)",
  "line_extract_group": 1,
  "button_command": "сменить {value}",
  "button_label_template": "Карта {value}",
  "max_buttons": 12,
  "cache_ttl": 300
}
```

### Дополнительные данные в ответе

Переменные доступны на платных тарифах, до 50 на чат. Scope analytics с правом записи нужен для переменной, commands — для текста команды. Значение передавайте строкой; переменная подставляется как |motd|.

1. POST /api/v1/variables
Создайте переменную один раз. При 409 она уже существует — используйте PUT.
```json
{
  "name": "motd",
  "value": "Турнир сегодня в 20:00",
  "description": "Анонс сообщества"
}
```

2. POST /api/v1/commands
Объедините своё значение и данные сервера в одном сообщении.
```json
{
  "com": "анонс",
  "vorker": "|motd|\n|server|",
  "custom": {
    "ip": "play.example.com:27015",
    "game_type": "cs16",
    "response_format": "plain"
  },
  "cooldown": 10
}
```

3. PUT /api/v1/variables
Ваш внешний сервис может менять текст без пересоздания команды.
```json
{
  "name": "motd",
  "value": "Турнир перенесён на 21:00"
}
```

Формат custom.response_format: auto — адаптация к платформе, plain — простой текст, native — родная разметка платформы. custom.notify_mentions=0 отключает уведомления. Доступны изображения custom.images и размещение before/inline_top/inline_bottom/after/gallery. Настройки и кнопки сохраняются объектом/массивом JSON; не вкладывайте пароль RCON или БД в custom.

## Scopes

- `nicknames`: Пользователи. Ники и поиск пользователей
- `commands`: Команды. Список команд, включение и выключение
- `ranks`: Ранги. Список рангов, назначение и снятие
- `analytics`: Аналитика. Активность, топы, модули, логи, usage
- `members`: Участники. Участники чата и публичный профиль
- `moderation`: Модерация. Баны, муты, автомод, наказания
- `settings`: Настройки. Настройки чата и модулей
- `welcome`: Приветствия. Чтение и изменение welcome
- `farewell`: Прощания. Чтение и изменение farewell
- `integrations`: Интеграции. Steam, ЮMoney, Twitch, VK Donut, SourceBans, FACEIT и другие подключения чата

## Настройки чата, команды и шаблоны

Панель настроек: https://gnrbot.ru/dashboard/settings. GET /api/v1/settings возвращает chat, automod и commands_count. PATCH: language (ru / en), global_cooldown (0–300 секунд), max_commands_per_minute (0–60), allow_standard_commands, allow_generator_commands, buttons_enabled (boolean). Отправляйте только изменяемые поля. Эти ограничения относятся к командам чата, не к квоте HTTP API.
GET /api/v1/commands: kind=all / standard / custom / rcon / active, limit=1–200, offset=0–100000. enabled управляет доступностью, show_in_list — отображением в списке; скрытая команда может оставаться рабочей.
PATCH /api/v1/commands: command, enabled и необязательные kind, show_in_list. Указывайте точное имя из GET. POST создаёт кастомную команду; PUT изменяет существующую. GET /commands?command=имя относится к кастомным командам; для стандартной — PATCH, для RCON — /rcon. Поля POST/PUT: com (имя), vorker (текст ответа, 1–4096 символов), description (до 255), category (до 50), cooldown (0–3600 секунд), required_rank, status (0/1), show_in_list (0/1), custom и buttons (JSON настроек). originalCom в PUT — старое имя при переименовании. Используйте числовые 0/1 в status и show_in_list POST/PUT.
PUT команды — сохранение формы с настройками по умолчанию, а не частичный PATCH: опущенные поля могут сброситься. Перед редактированием выполните GET /api/v1/commands?command=точное_имя. Ответ data содержит vorker, custom, buttons, role_ids, rank_group_ids, deny_action, deny_message, alias_for, button_response_mode и другие поля для PUT. Передайте этот объект целиком, изменив только нужное. Для одного переключателя используйте PATCH.
В тексте команды доступны подстановки конструктора, например {1} — первый аргумент. Наборы подстановок различаются у команды, приветствия, RCON и интеграции: не переносите их между разделами без предпросмотра. Имена и ссылки на людей проверяйте в целевой платформе; отображение и уведомления зависят от VK, Telegram или Discord.
GET /api/v1/formats возвращает сохранённые command_type, format_key, format_value, is_enabled. PATCH меняет одну пару command_type + format_key; format_value — до 2000 символов. Дополнительно GET возвращает defaults — системные образцы с реальными ключами и подстановками. Пустой data означает отсутствие переопределений. PATCH принимает также is_enabled (boolean). Выбирайте пары из defaults или существующего data; произвольная пара может сохраниться, но не использоваться ботом.
POST /api/v1/variables создаёт переменную: name (1–50 букв, цифр и _), value (строка до 2000), description (до 255). Требуется платный тариф; максимум 50 на чат. Системные имена запрещены, повторное создание — 409. Подстановка в ответ: |motd|. GET /api/v1/variables читает переменные. PUT меняет существующую переменную: name (1–100 символов), value (до 2000). Создайте переменную в панели заранее; отсутствующее имя даёт 404. Текущий обработчик выполняет обновление, хотя краткое описание общего каталога может упоминать создание.
GET/PATCH /api/v1/images: command и images (массив до 10 HTTPS URL, каждый до 500 символов, без пробелов и угловых скобок). Это полная замена массива; [] удаляет изображения. После PATCH проверяйте сохранённый список через GET.
GET/PATCH /api/v1/welcome и /farewell: is_enabled, message_text (до 2000 символов), use_name. Для welcome также поддерживается welcome_rank_id — существующий ID ранга чата, null снимает назначение. Картинки и кнопки приветствий настраивайте в панели: v1 сохраняет прежние значения, но не редактирует их.

## Игровые модули

Панель модулей: https://gnrbot.ru/dashboard/modules. GET /api/v1/modules показывает enabled, cache_enabled, commands, supports_top и supports_users. PATCH принимает только module и enabled. Детальные настройки ниже меняются в карточке модуля в панели; передача config в публичный PATCH не является поддержанным способом настройки.
Для топа: GET /api/v1/modules/top?module=clans&limit=10 (scope analytics). Для участников: GET /api/v1/modules/users?module=clans&page=1&limit=50; доступны search и noNick=1, limit до 100. Это пагинация page, а не offset. Сначала проверьте supports_top / supports_users. Пустой ответ может означать отсутствие накопленных данных.

- **Репутация** (`reputation`): Карма и благодарности. Команды: «спасибо», «репутация», «топреп». Настройки панели: cooldown_hours — интервал благодарностей в часах; max_daily — дневной предел.
- **Развлечения** (`fun`): Шар, монетка, рандом, кости. Команды: «шар», «монетка», «рандом», «выбери», «кости». Настройки панели: dice_max — максимум кубиков; random_max — верхняя граница случайного числа.
- **Цитатник** (`quotes`): Цитаты участников. Команды: «цитата», «цитаты». Настройки панели: max_quotes — предел цитат; allow_anonymous — анонимные цитаты.
- **Ежедневные награды** (`daily_rewards`): Ежедневный бонус и стрик. Команды: «ежедневка», «серия», «топсерия». Настройки панели: base_reward — базовая награда; streak_bonus — процент бонуса серии.
- **Игры** (`games`): Мини-игры и статистика побед. Команды: «кнб», «угадай», «дуэль», «викторина», «игростат». Настройки панели: guess_max_attempts — попытки угадывания; trivia_timeout_sec — время викторины в секундах.
- **Уровни** (`levels`): XP и уровни за активность. Команды: «уровень», «топуровень». Настройки панели: xp_min / xp_max — диапазон XP; xp_cooldown_sec — интервал начисления.
- **Предсказания** (`predictions`): Голосования да/нет. Команды: «предсказание», «предсказания». Настройки панели: max_active — предел активных предсказаний.
- **Опросы** (`polls`): Голосования с вариантами. Команды: «опрос», «голос», «итогиопрос». Настройки панели: max_options — число вариантов; max_active_polls — предел активных опросов.
- **Экономика** (`economy`): Виртуальная валюта. Команды: «баланс», «передать», «топбаланс». Настройки панели: currency_name — название валюты; message_reward — награда за сообщение; transfer_enabled — переводы.
- **Достижения** (`achievements`): Значки за активность. Команды: «достижения», «значки». Настройки панели: notify_unlock — уведомления о новых достижениях.
- **Игра в слова** (`wordgame`): Слова и анаграммы. Команды: «слово», «анаграмма», «словостат». Настройки панели: word_length_min / word_length_max — длина слова; max_attempts — число попыток.
- **Браки** (`marriages`): Пары в чате. Команды: «брак», «развод», «пары». Настройки панели: Дополнительных полей конфигурации в карточке нет.
- **Гороскоп** (`horoscope`): Ежедневный гороскоп. Команды: «гороскоп», «знакзодиака». Настройки панели: Дополнительных полей конфигурации нет; знак задаётся командой участника.
- **Дни рождения** (`birthdays`): Дни рождения участников. Команды: «деньрождения», «ближайшиедр». Настройки панели: Дополнительных полей конфигурации нет; дату задаёт участник.
- **Лотерея** (`lottery`): Розыгрыши и билеты. Команды: «лотерея», «билет», «розыгрыш». Настройки панели: default_ticket_price — цена билета.
- **Кланы** (`clans`): Кланы, участники и топ. Команды: «клан», «кланы», «кланстат». Настройки панели: max_members — предел участников; join_mode — open / invite; top_sort — total_messages / member_count / server_stats; top_limit — размер топа; stats_server_id — ID источника (0 — единственный доступный); stats_metric — kills / deaths / headshots / skill / gametime / score.

## Серверы статистики и кланы

Панель: https://gnrbot.ru/dashboard/stats-servers. Подключение статистики, RCON-сервер и чат — разные сущности. ID статистики берите из GET /api/v1/stats-servers, ID RCON — из capabilities.rcon_servers; не подставляйте один вместо другого, даже если названия совпадают.
1. Выберите чат и добавьте источник в «Серверах статистики»: тип статистики, адрес игрового сервера, параметры БД. Для произвольной SQL-статистики сопоставьте таблицу и поля через редактор схемы. Проверьте подключение и найденную таблицу.
2. Включите источник и проверьте чтение статистики игрока и топа. Мониторинг онлайна без SQL-статистики сам по себе не даёт убийства, смерти или игровой рейтинг.
3. Включите clans. Режим вступления, лимит участников и способ расчёта топа задаются в карточке модуля. Участники должны создать кланы и вступить в них, иначе топ будет пустым.
4. Для игрового топа участники указывают точный игровой ник, затем при возможности SteamID. В настройках clans выберите top_sort=server_stats, stats_server_id нужного SQL-источника и stats_metric (по умолчанию kills). Значение stats_server_id=0 выбирает единственный доступный источник; при нескольких выберите конкретный ID.
Команды бота: «кланы серверы» — доступные источники; «кланы стата [ID] [показатель]» — игровой топ; «кланстат стата [ID] [показатель]» — статистика своего клана. Без «стата» используется top_sort модуля. score требует настроенную player_score_formula источника. Статистика считается суммой показателей текущих участников за всё накопленное время источника, а не с момента вступления в клан. Кланы могут быть общими в группе чатов; источник статистики выбирается строго из текущего чата.
При включении clans автоматически создаётся дополнительное поле SteamID с командой «стим». «клан» показывает состав по 8 участников со страницами и кнопками. «клан помощь» — команды; «клан профиль» — игровой ник и привязка; «клан ник ВашНик» — точный ник из игры; «клан стим STEAM_0:1:12345» или «steam <SteamID64>» — явная привязка. «клан стим отвязать» очищает привязку и связанные значения поля. Редактируемые команды полей с ключами steam_id, steamid, steam и gnr_steam используют ту же привязку.
Без привязки статистика ищется по точному нику; при однозначном свежем снимке игрового сервера — по найденному SteamID. Явный SteamID всегда приоритетнее ника. Совпадающие ники и игровые профили не дают двойной вклад. «клан профиль» подсказывает SteamID из снимка, но права в плагине появляются только после явной привязки. Ник не доказывает владение аккаунтом. Занятый SteamID нельзя забрать у другого профиля; для своих профилей используйте «склейка».
Кланы 2.4 передают player_names (до 32 пар steamid/name). API хранит только последний состав, без истории. Для подсказок используются снимки младше 120 секунд; Bridge также подходит. Старые версии синхронизируют привязки как раньше, но без новых подсказок по имени. Русские показатели: убийства, смерти, хедшоты, скилл, время, очки; английские названия сохраняются.
Игровой топ обновляется с кэшем около минуты; для HLstatsX без поля authid сопоставление по Steam недоступно. Публичный GET /api/v1/modules/top?module=clans пока возвращает чатовый топ по сообщениям/составу, не игровой топ. Игровую статистику кланов вызывайте командами бота; не интерпретируйте чатовый total_messages как kills.
GET /api/v1/stats-servers возвращает до 40 подключений без паролей БД. PATCH принимает id и is_active (boolean), только переключает существующее подключение. Подключение источника, пароль и сопоставление столбцов настраиваются в панели. Команды доступны через GET/POST/PUT/DELETE /api/v1/stats-commands (scope commands): stats_server_id из /stats-servers, command_name, command_type (top/player_stats/server_info/server_online/custom), template, response_format (detailed/list/compact/custom), top_limit (1–50), sort_field, sort_order (ASC/DESC), score_formula, score_label, required_rank, cooldown, buttons, notify_mentions, is_enabled, show_in_list. Формула для top, например kills / max(deaths, 1), проверяется как арифметическое выражение, SQL через неё не передаётся. POST возвращает data.id; PUT требует id, пропущенные поля сохраняются; DELETE принимает JSON {id}. Максимум 50 команд на чат.
GET /api/v1/stats?period=7d&limit=10 возвращает servers, topPlayers, topKills, summary, meta. period (1d / 7d / 30d / 90d) относится к сессиям мониторинга. topKills — накопительные kills/deaths из внешней БД, а не убийства только за период. Смотрите meta.kills_note и meta.kills_cached. Пустой топ проверяйте по подключению, схеме источника и данным.

## RCON и автокнопки

В панели заранее добавьте RCON-сервер, проверьте подключение, допустимые команды и ранги исполнителей. Публичное API не исполняет RCON: оно сохраняет настройки. GET /api/v1/rcon возвращает конфигурации без паролей; POST создаёт, PUT изменяет по id, DELETE удаляет по id. PATCH {command, enabled} переключает существующую команду. Максимум 50 RCON-команд на чат.
Автокнопки разбирают вывод RCON-команды и подставляют найденные значения в команды кнопок. GET /api/v1/auto-buttons возвращает полные настройки парсера без кэша результатов. На чат допускается до 30 конфигураций.
POST /api/v1/auto-buttons: name, source_command, button_command; source_rcon_command_id выбирает существующую команду-источник. Для создания источника явно передайте ensure_source: true, source_rcon_server_id и create_source_name. При нескольких серверах выбирайте ID явно. Если источник с таким именем уже существует, будет использован он: новый ID сервера не переносит существующую команду на другой сервер.
ensure_target: true разрешает создать текстовую команду-заглушку из первого слова button_command. Это не готовая команда бана, выдачи привилегии или смены карты. Создайте целевую RCON-команду и её права через POST /rcon или в панели. Явно задавайте ensure_source и ensure_target: чтобы намерение запроса было однозначным.
Парсер: parse_mode (simple / advanced), skip_first_lines и skip_last_lines (0–100), line_regex (до 512 символов), line_extract_group (0–20), delimiter (до 64), trim_lines (0/1), advanced_regex (до 1024), advanced_flags (например gm). В режиме advanced нужно корректное регулярное выражение. button_label_template содержит {value}; max_buttons — 1–50; cache_ttl — 0–86400 секунд (обычно 300). Ненулевой кэш уменьшает повторные запросы к игровому серверу.
PUT /api/v1/auto-buttons требует id. GET возвращает полную конфигурацию; PUT сохраняет пропущенные поля. После изменения проверьте предпросмотр парсера и вызов команды в чате.

## Интеграции: каталог, настройки и проверка

Панель: https://gnrbot.ru/dashboard/integrations. GET /api/v1/integrations (scope integrations) возвращает planKey, providers, accounts. В providers проверяйте id, account, configure, minPlan, locked. account: true означает настройку через PATCH /api/v1/integrations; account: false — отдельную карточку панели, не допустимый provider этого PATCH. Отсутствующая карточка может быть скрыта администратором.
accounts: provider, enabled, config, hasSecret, lastSyncAt, lastError, notifyUrl. hasSecret подтверждает наличие сохранённого секрета, но не его работоспособность. API не возвращает секреты; хранение использует AES-256-GCM.
PATCH принимает provider, enabled?, config? (JSON-объект), secret? (до 256 символов). Поля config объединяются с сохранёнными; массивы, например streamers, заменяются целиком. Пропущенные enabled и secret сохраняют прежние значения. Пустой secret не удаляет сохранённый секрет. Токены и пароли передавайте в secret, не в config.
При первом подключении передайте все обязательные поля, секрет и enabled: true. У существующего меняйте отдельные поля config. Отключение: {provider, enabled:false}; настройки остаются. Для нового аккаунта даже выключенное подключение должно пройти валидацию обязательных полей.
Не используйте API-ключ GNR Bot вместо секрета провайдера. Не публикуйте секреты и реальные notifyUrl в примерах или сообщениях чата.

### Кланы CS 1.6 — clans

Кланы бота в игре: лицензии, префиксы, нативы, уровни и бонусы
Настройка в панели: https://gnrbot.ru/dashboard/integrations?provider=clans

### GameCMS — gamecms

Сайты, услуги, статистика и секция в профиле бота
Настройка в панели: https://gnrbot.ru/dashboard/integrations?provider=gamecms

### CS 1.6 — cs16

Игроки, привилегии, бан, кик и мут с кнопками в чате
Настройка в панели: https://gnrbot.ru/dashboard/integrations?provider=cs16

### Steam — steam

SteamID64, VAC и игровое время в профиле и топе
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: free; действующий — из providers[].minPlan.
config: profileField (2–32 строчных латинских символа, цифры, _ или -, по умолчанию steam), appId (1–999999, по умолчанию 10). secret: Steam Web API ключ. Участник привязывает SteamID командой «steam STEAM_0:1:12345» или «steam <SteamID64>».

### DonationAlerts — donationalerts

Оповещения донатов в чат, валюта экономики и товары
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: free; действующий — из providers[].minPlan.
config: currencyPerRub (0–100000, по умолчанию 10), alertChat (boolean, по умолчанию true), matchNicks (boolean, по умолчанию true). secret: токен DonationAlerts. alertChat управляет сообщениями о донатах, поэтому уведомления этой интеграции не выключены по умолчанию. Для начислений нужна настроенная экономика; товары настраиваются в панели.

### ЮMoney — yoomoney

Покупка привилегий через кошелёк и RCON. Отдельный URL уведомлений на чат или группу
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: free; действующий — из providers[].minPlan.
config: wallet (строка из 11–20 цифр), successMessage (необязательный текст до 240 символов). secret: секрет уведомлений ЮMoney. После сохранения скопируйте полученный notifyUrl в настройки уведомлений кошелька. Товары, суммы, выдача через экономику или RCON и выбор общей группы настраиваются в панели. Публичный v1 меняет подключение текущего чата, не создаёт товары и платежи.

### Twitch — twitch

Алерт в чат, когда стрим сервера, админа или выбранных каналов выходит в эфир
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: starter; действующий — из providers[].minPlan.
config: clientId (8–64 латинских символа или цифры), streamers (до 20 записей), liveTemplate (до 240 символов, по умолчанию 🔴 {name} начал стрим: {url}), includeAdminStreams (boolean, по умолчанию true). Запись streamers: {login, chatId?, template?}; login — 3–25 строчных латинских символов, цифры или _. chatId здесь — UUID чата назначения алерта. secret: Client Secret приложения Twitch.

### VK Donut — vkdonut

Донат-подписка сообщества VK как источник привилегий
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: starter; действующий — из providers[].minPlan.
config: groupId (ID сообщества из 3–20 цифр), privilege (до 64 символов, по умолчанию VK Donut), rcon (необязательный шаблон до 240 символов). secret: ключ сообщества VK. До включения выдачи проверьте шаблон привилегии и RCON-сервер в панели.

### SourceBans / AMXBans — sourcebans

Синхронизация банов CS 1.6 с веб-банлистом и командами в чате
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: starter; действующий — из providers[].minPlan.
config: engine (sourcebans / amxbans), host (хост MySQL без протокола), port (1–65535, по умолчанию 3306), database, username (непустые строки до 64 символов), prefix (до 16 латинских символов, цифр или _, по умолчанию sb_), commandName (2–32 символа, по умолчанию банлист). secret: пароль MySQL. Для AMXBans укажите фактический префикс таблиц, не копируйте sb_ автоматически.

### FACEIT — faceit

Привязка аккаунта и ELO в профиле для CS-сообществ
Настройка: PATCH /api/v1/integrations. Базовый минимальный тариф: starter; действующий — из providers[].minPlan.
config: game (cs2 / csgo, по умолчанию cs2), showInProfile (boolean, по умолчанию true). secret: FACEIT Data API key. Участник привязывает аккаунт командой «faceit <ник>».

### CS мониторинги — cs-monitors

Бусты и круги с рейтингов gdeboost, csstats и listsms. JSON SVV Monitor Engine, иначе HTML
Настройка в панели: https://gnrbot.ru/dashboard/integrations?provider=cs-monitors

### Discord Roles sync — discord-roles

Ранги панели ↔ роли Discord через основного бота, без личного бота
Настройка в панели: https://gnrbot.ru/dashboard/integrations?provider=discord-roles

CS мониторинги: добавьте адрес сервера и при необходимости включите уведомления по почте. Карточка показывает источники, бусты, круги, сроки и lastRefreshAt / lastError. Плановый цикл — около 5 минут, при недоступных источниках возможны задержки; ручное обновление — не чаще раза в 30 секунд. Это учёт продвижения на внешних мониторингах, не источник SQL-статистики для топа кланов.

## Кланы CS 1.6 — отдельная интеграция и GNR Clans 2.2

В модуле «Кланы» источник игровой статистики выбирается из выпадающего списка активных SQL-серверов текущего чата. Автовыбор доступен для единственного источника. Недоступный ранее выбранный сервер отмечается отдельно; ID вручную вводить не нужно.
Кланы 3.0: новая экосистема включается eco_enabled=1 в configs/gnr/gnr_clans.ini и gnr_clans_reload. Первый включённый сервер задаёт общие правила; источник можно сменить в панели. Остальные серверы получают правила из API. Боевые эффекты требуют включённых бонусов в панели. Только обычный CS 1.6, AMXX 1.9, Easy HTTP и стандартный hamsandwich. INI и lang создаются самим .amxx, отдельные файлы доступны в скачиваниях.
Экосистема использует /v1/clans/ecosystem: приглашения, состав, роли, покупки, турниры, задания, события, боевые результаты. Код в Authorization: Bearer, обязательны port/installation/protocol/nonce/event_id/sent_at. Повтор event_id допускается только с тем же действием; запросы старше 120 с отклоняются. Сервис проверяет IP и подписку, состав/права/приглашение/остаток очков транзакционно. Вступление при включении экосистемы только по приглашениям, и в игре, и в чате.
Роли до 16: приоритет 1–200, тип custom/deputy/elder, свой лимит и маска 1 депозит, 2 расход казны, 4 личные бонусы, 8 определения ролей, 16 приглашение, 32 исключение младших, 64 назначение младших ролей, 128 заместители, 256 передача главы, 512 развитие, 1024 турниры, 2048 улучшения. Глава имеет 4095; определения ролей, заместителей и главу в игре меняет только глава. Назначения не могут выдавать отсутствующие права или воздействовать на равных/старших. Лимиты заместителей/старшин общие из INI.
Очки развития общие для серверов, отдельно от XP/казны. Журнал: причина, инициатор, delta, до/после, время; хранится eco_ledger_days=90 (14–365), баланс и награды не очищаются. Кланы покупают HP, броню, урон, регенерацию, места, тихий нож и переименование. VIP/weapon — эффекты SDK для внешних дополнений, флаги админов/готовое оружие автоматически не выдаются. Настройки цен/уровней/названий/порядка в том же INI; тексты — data/lang/gnr_clans.txt.
Турниры: вызов, принятие/отказ, цель, ставка, таймер, победитель. Ставки резервируются и возвращаются при отказе/ничьей/распаде/отмене. API считает только убийства противника по турниру, разных игровых команд; без ботов и фарма одной пары, минимум игроков настраивается. Задания kills/knife/wins/points/recruits имеют стабильный ID; награда за ID однократна. Админ: gnr_clans_ecoadmin points ID +/-СУММА ПРИЧИНА | quest ID 0/1 | finish ID | delete ID confirm | cleanup.
Команды бота экосистемы: клан развитие; клан улучшения; клан купить health; клан задания; клан турниры; клан вызов TAG 50 100; клан принять НОМЕР; клан отклонить НОМЕР; клан боевойтоп; клан активность; клан приглашения вкл/выкл. Ответом участнику: клан пригласить/исключить/роль 2/глава. В игре: /clan, /claninvites, /clanupgrades, /clanquests, /clanwar, @clan текст. SDK: 69 нативов, новые изменения подтверждаются gnr_clans_ecosystem_result; неизвестный исход сначала проверять чтением.
Новая интеграция: https://gnrbot.ru/dashboard/integrations?provider=clans . Включите модуль «Кланы», создайте подключение (название, внешний IPv4 и игровой порт; до 10 серверов в чате, каждому отдельный API-ключ), сохраните уникальный код и скачайте готовый gnr_clans.amxx. По умолчанию требуется Pro; минимальный тариф и видимость настраиваются администратором сайта в интеграциях. Проверка подписки, кода и включённого модуля выполняется сервером при синхронизации.
Установите AMXX 1.9 и Easy HTTP с рабочими TLS CA. Добавьте gnr_clans.amxx в plugins.ini, отключите старый gnrbot_cs16_clans.amxx для исключения повторных команд. Bridge для новой интеграции не требуется. На первой карте создаются configs/gnr/gnr_clans.ini, инструкция TXT, gnr_clans_bonuses.ini для прежних личных бонусов и data/lang/gnr_clans.txt. Вставьте код своего сервера в license и внешний игровой порт в server_port, выполните gnr_clans_reload. API проверяет IP сетевого соединения, а не адрес из Docker/плагина. Исходящий IPv4 должен совпадать с outbound_ip из панели (либо server_ip, если outbound_ip не задан). Исправление outbound_ip сохраняет ключ; перенос уже привязанного игрового IP/порта заменяет ключ. Код связывается с первой установкой; перенос на другой сервер — через замену кода в панели. Код показывается только при создании/замене, на сайте хранится его хеш.
Easy HTTP обязателен для всех плагинов. Официальные сборки Linux/Windows: https://github.com/Next21Team/AmxxEasyHttp/releases/latest . Установите модуль и CA-файл, проверьте amxx modules. История версий есть внизу обеих интеграций и в поле history манифеста /v1/plugins/{id}/1.9.
Bridge 1.8.1: единый INI [настройки], [получатели], [привилегии]; старые конфиги импортируются один раз. gnrbot_cs16.txt рядом содержит команды и права; обновляется без замены INI. logs/gnr содержит два файла по 1 МиБ на плагин. В каждом режиме действует heartbeat <=60 секунд. Команды kick/ban/mute подтверждаются action_results, привязаны к session_id и userid; просроченные через 90 секунд отменяются. Бот отправляет результат в чат.
Кланы 3.0 сохраняют функции 2.5: endpoint зашит; русский INI, menu_title/menu_order/menu_* и deposit_amount; TXT рядом с командами. Каталог до 200 кланов хранится в data/gnr/clans-catalog.json, не более 128 КиБ; SHA-256 исключает повторную передачу и запись неизменных данных. Обновление данных применяется без смены карты. /clancatalog — каталог и вступление; /clanleave — выход с подтверждением; gnr_clans_refresh — обновить данные. В карточке ранга доступно назначение существующих рангов онлайн-участникам главой; назначения из меню экосистемы учитывают расширенные права и иерархию. Полный состав загружается страницами, кэш не даёт прав на казну и бонусы без свежей синхронизации. server_ip — игровой IPv4, по которому заходят игроки; outbound_ip — необязательный подтверждённый IP исходящего HTTPS за NAT. Например, server_ip=45.95.31.209, server_port=27015, outbound_ip=45.95.31.204. API определяет IP соединения и сообщает observed_ip/expected_ip. Исправление outbound_ip сохраняет ключ и привязку установки; перенос уже подключённого сервера на другой игровой IP/порт или явная замена кода отзывает прежний ключ. Диагностика прежнего адреса сбрасывается.
Меню кланов и управления CS16 в чате имеют кнопку Закрыть; кнопки снимаются через 60 секунд без взаимодействий. Перед киком, баном или текстовым мутом выберите причину (либо игроки причина Ваш текст), для бана/мута — срок, затем подтвердите. Бан 0 минут — навсегда; мут прекращается также при переподключении/смене карты. В списке ники добавляются разрешённые к показу дополнительные поля, включая SteamID.
HTTP 401 в клановом плагине: ключ неверен, отозван или подключение отключено; IP ещё не проверяется. Вставьте действующий ключ в license файла configs/gnr/gnr_clans.ini и выполните gnr_clans_reload. Если ключ утерян, замените код в панели. HTTP 403 IP_MISMATCH: уточните у хостинга IP HTTPS и задайте outbound_ip, игровой адрес менять не нужно. PORT: исправьте server_port. INSTALLATION: ключ связан с другой установкой. gnr_clans_status 2.5.0+ показывает короткий отпечаток ключа для сравнения с панелью; ключ не публикуйте. После reload обновите статус в панели. Плагин пишет об успешной синхронизации и смене ошибки в logs/gnr/clans.log, не засоряя журнал одинаковыми повторами.
Bridge 1.8.1 отправляет снимки в https://api-modules.gnrbot.ru/v1/cs16/ingest . Старый https://api.gnrbot.ru/api/integrations/cs16/ingest работает как переходный прокси. Обработчик, лимит 4 запросов и пул 2 MySQL-соединений живут в отдельной службе. gnrbot_cs16_clans.sma в ZIP — исходник дополнения отображения; устанавливается gnrbot_cs16_clans.amxx после Bridge. Это не самостоятельный gnr_clans.amxx: ранги, казна, уровни и бонусы доступны в интеграции clans.
GNR Clans 3.0 рассчитан на обычный CS 1.6. Уровни, XP, банк и бонусы готовы, но выключены по умолчанию. Разрешите нужные функции в подключении панели; старые levels/bank/bonuses в INI игнорируются. xp_per_level и max_level задаются в панели; xp_per_kill и xp_headshot — в INI. Боты, самоубийства и своя команда XP не дают. Состав общий с ботом. Настройка game_creation_enabled (по умолчанию false) разрешает /clancreate ТЕГ Название и /clanjoin ТЕГ для открытых кланов при выключенной экосистеме; при eco_enabled — только по приглашению. До привязки участник показывается игровым ником без социальной ссылки; клан стим STEAM_0:1:12345 объединяет профиль и сохраняет членство, лидерство и ранг. Чужой SteamID или разные кланы вызывают отказ без перезаписи.
Хранилище прогресса: bot — БД бота через HTTPS без выдачи пароля; mysql — собственная БД из секции mysql INI, асинхронный SQLX, отдельная таблица gnr_clan_local_progress. Смена хранилища не переносит данные: сначала опустошите очередь. Не копируйте пароль БД бота в игровой сервер. Состав в обоих режимах приходит из модуля бота.
Префикс prefix поддерживает {tag}, {name}, {level}, {rank}; его получает чат-плагин нативом gnr_clans_get_prefix. SDK gnr_clans.inc скачивается отдельно; доступно 69 нативов с русскими описаниями: состав, тег, имя, роль, лидер, онлайн, XP, уровень, банк, ранг, топ, состояние, обновление, меню, операции и регистрация валют. gnr_clans_add_xp и gnr_clans_change_bank возвращают ID очереди; подтверждение — forward gnr_clans_operation_result (1 успех, 0 отказ, -1 неизвестный результат локального SQL). Не начисляйте возврат и не повторяйте неизвестную SQL-запись вслепую.
Валюта currency=csmoney или зарегистрированный аддоном провайдер через gnr_clans_register_currency. Банк — виртуальные очки, не покупки и не реальные деньги. Меню бонусов конфигурируется строками key, название в кавычках, min_level, price, effect, amount, uses_per_round. Эффекты health, armor, gravity; HP/AP до 200, гравитация 50–100%. Оплата валютой игрока, не банком; проверяются жизнь, уровень и лимиты. Перед/после покупки вызываются forwards для расширений. ZM и готовый адаптер ammo packs в первой версии не включены.
Игровые команды новой версии: /clan, /clans, /clantop, /clanbonus, /clandeposit; консоль gnr_clans_deposit 500, gnr_clans_admin, gnr_clans_status, gnr_clans_reload. Админ-флаг по умолчанию h, меняется в INI. Топ плагина — XP (при выключенных уровнях в bot-режиме сообщения), собственная MySQL — ранее накопленный XP. Для топа по убийствам источника статистики используйте кланы стата в боте; публичный /modules/top его не заменяет.
Отдельный процесс gnrbot-modules обслуживает синхронизацию; падение службы не останавливает бота. Рабочий URL https://api-modules.gnrbot.ru/v1/clans/sync ; /v1/clans/game — создание/вступление, /v1/clans/roster — свой состав по 7 участников со статусом онлайн на сервере. Синхронизация каждые 30 секунд или в начале раунда, не чаще 6 секунд. HTTPS reverse proxy направляет запросы на отдельную службу 192.168.1.202:6000. Внутренний порт 4400 сохранён. Старый API-адрес совместим. Выбор AMXX: 1.9 доступна, 1.10 и 1.8.2 отмечены как будущие сборки. updates в INI: 0 выключено, 1 установка командой gnr_clans_update (по умолчанию), 2 автоматически. Проверка версии при старте карты; бинарник проверяется по размеру и SHA-256, сохраняется одна предыдущая версия, новая загружается на следующей карте. Конфиги не заменяются.
Ограничения: до 10 кодов на чат, один HTTP-запрос на плагин, обычно раз в 30 секунд (с очередью раз в 6 секунд), таймаут 10 секунд, backoff до 300 секунд, данные устаревают через 120 секунд. До 32 игроков, топ до 20, очередь до 64 событий, 16 на запрос, срок события час. Облачные изменения идемпотентны; при локальном SQL неясный результат не повторяется. Смена карты может прервать локальное подтверждение; userid и возвраты денег CS через карту не восстанавливаются. Для надёжного повтора используйте bot-хранилище.

Ранги: до 16 своих рангов на клан через Интеграции → Кланы CS 1.6 → Ранги, права и казна. Права: пополнение 1, расход 2, бонусы 4, управление рангами 8; маска до 15. Лидер сохраняет все права. Без своего ранга участник имеет пополнение и бонусы. Удаление ранга возвращает базовые права; выход из клана удаляет назначение. Эти права относятся к игровым функциям; команды состава бота сохраняют собственные правила. Нативы get_member_rank/get_rank_name/get_permissions/has_permission/get_rank_count/get_rank_info/save_rank/delete_rank/set_member_rank с префиксом gnr_clans_. get_rank по-прежнему означает место в топе, а не свой ранг. Казна: treasury_deposit/treasury_spend; они не меняют кошелёк игрока и требуют асинхронного подтверждения.
Аналитика → Интеграции показывает все настроенные включённые провайдеры текущего чата и связанных групп: состояние, последнее обновление, события/ошибки за 24 часа там, где они измеряются. Для Discord отображаются настроенные связи без выдуманного результата синхронизации. Секреты и webhook payload не выдаются, отдельная история опросов не пишется.
Плагины CS 1.6 выделены в категории интеграций. Рядом с .amxx скачиваются русский SDK и лёгкий knz_version.inc для размещения рядом с knz_license.inc: проверка версии без лицензирования/записи файлов. Bridge обновляется командой gnrbot_cs16_update, режим gnrbot_cs16_plugin_updates 0/1/2; дополнительный viewer — gnrbot_cs16_clans_update и gnrbot_cs16_clans_plugin_updates.

## Старый дополнительный плагин кланов Bridge (совместимость)

Включите «Кланы» у выбранного чата, откройте «Интеграции → CS 1.6» и скачайте архив. Установите gnrbot_cs16.amxx (Bridge) и затем gnrbot_cs16_clans.amxx после него в plugins.ini; смените карту. Подключение использует свой ключ CS16 из панели, не ключ публичного v1.
Игровая команда /clan показывает свой клан и его участников онлайн; /clans — игроков с кланами на этом сервере. Полные строки выводятся в консоль игрока. Эти команды не являются игровым топом по убийствам и не выгружают весь состав группы. Создание клана, вступление и привязка Steam выполняются в чате бота.
Настройки в configs/gnr/gnrbot_cs16.ini: clans_enabled = 1; clans_source = 1. source — номер действительного уникального ключа в [получатели] (1–10); при одном ключе — 1. Модуль должен быть включён в чате выбранного ключа. Дополнительного HTTP-опроса нет: данные приходят с обычным снимком Bridge. Устаревшие данные скрываются через 120 секунд; отключение модуля применяется после следующего успешного снимка.
Сопоставление игроков — по SteamID и привязке SteamID64; VALVE, LAN, pending и боты не сопоставляются. Плагин не меняет ники и не выдаёт привилегии. Отображение клана не подтверждает личность игрока на сервере, где можно подделать SteamID.
После сохранения интеграции дождитесь рабочего цикла, проверьте lastSyncAt / lastError, затем профиль, банлист или алерт в нужном чате. Фоновые воркеры получают данные и создают события для бота; enabled: true само по себе не проверяет секрет, запущенный воркер и доступность внешнего сервиса.

## Свои боты, профили, ранги и модерация

Личные боты подключаются на https://gnrbot.ru/dashboard/custom-bots. У бота VK есть feature key vk_wall_repost: репост новых записей стены сообщества в одобренные чаты. Это стена сообщества, не личная страница; настройка выполняется в панели. plugins в capabilities описывает возможность, но не подтверждает настройку конкретного бота.
GET /api/v1/profile?platform=tg&user_id=<ID> (scope members); также допустимы vk и ds. ID пользователей передавайте строками. «склейка» связывает профили платформ, «steam» привязывает игровой SteamID64. Привязка чата к панели и привязка Steam пользователя — разные операции.
GET /api/v1/ranks возвращает ранги и назначения. POST назначает/снимает существующий ранг: platform (vk / telegram / discord), platformUserId (строка), rankId; action: revoke снимает ранг. Ключу нужны права записи ranks. Настройку самих рангов и массовые действия выполняйте в панели.
GET /api/v1/moderation и /punishments читают наказания. PATCH /api/v1/automod переключает существующее правило: ruleId, enabled. Публичный v1 не предоставляет произвольное выполнение чат-команды бана или мута; используйте чат и панель с соответствующими правами.
Подписки: https://gnrbot.ru/dashboard/subscriptions. Проверяйте доступность функции для выбранного чата, а не только общий список возможностей продукта.

## Примеры запросов

Начните с capabilities. Пример для серверного Node.js: GNR_API_KEY задаётся через окружение; не вставляйте ключ в страницу.

```javascript
const api = "https://api.gnrbot.ru/api/v1";
const key = process.env.GNR_API_KEY;
if (!key) throw new Error("Задайте GNR_API_KEY");
const response = await fetch(`${api}/capabilities`, { headers: { "X-API-Key": key }, signal: AbortSignal.timeout(10000) });
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error || "Ошибка API"}`);
console.log({ chat: result.chat_id, plan: result.plan, scopes: result.modules });
```

Ниже тела отдельных запросов; добавьте тот же X-API-Key и Content-Type: application/json. Числовые ID и example.com — демонстрационные значения, замените их данными своего чата. Примеры не выполняются автоматически.

### Ограничить частоту команд чата

`PATCH /api/v1/settings`

```json
{
  "global_cooldown": 3,
  "max_commands_per_minute": 20,
  "buttons_enabled": true
}
```

### Создать текстовую команду

`POST /api/v1/commands`

```json
{
  "com": "правила",
  "vorker": "Уважайте участников и не флудите.",
  "description": "Правила чата",
  "category": "general",
  "cooldown": 10,
  "status": 1,
  "show_in_list": 1
}
```

### Скрыть команду из списка, сохранив возможность вызова

`PATCH /api/v1/commands`

```json
{
  "command": "правила",
  "kind": "custom",
  "enabled": true,
  "show_in_list": false
}
```

### Включить кланы

`PATCH /api/v1/modules`

```json
{
  "module": "clans",
  "enabled": true
}
```

### Настроить приветствие

`PATCH /api/v1/welcome`

```json
{
  "is_enabled": true,
  "message_text": "Добро пожаловать, {name}! Правила: команда «правила».",
  "use_name": true
}
```

### Изменить существующее подключение Steam

`PATCH /api/v1/integrations`

```json
{
  "provider": "steam",
  "config": {
    "profileField": "steam",
    "appId": 10
  }
}
```

Сохранённые secret и enabled остаются прежними. Для первого подключения добавьте свой secret и enabled: true в приватном запросе.

### Отключить существующую интеграцию

`PATCH /api/v1/integrations`

```json
{
  "provider": "twitch",
  "enabled": false
}
```

Пример предполагает уже сохранённый Twitch config. Настройки и секрет не удаляются.

### Заменить изображения команды

`PATCH /api/v1/images`

```json
{
  "command": "правила",
  "images": [
    "https://example.com/rules.png"
  ]
}
```

Замените демонстрационный URL адресом своего изображения; images: [] очищает список.

### Создать автокнопки из списка карт

`POST /api/v1/auto-buttons`

```json
{
  "name": "Карты сервера",
  "source_rcon_server_id": 1,
  "create_source_name": "карты",
  "source_command": "maps *",
  "ensure_source": true,
  "ensure_target": true,
  "parse_mode": "simple",
  "line_regex": "([a-zA-Z0-9_]+)\\.bsp",
  "line_extract_group": 1,
  "trim_lines": 1,
  "button_command": "выбраннаякарта {value}",
  "button_label_template": "{value}",
  "max_buttons": 20,
  "cache_ttl": 300
}
```

Замените source_rcon_server_id: 1 на ID из capabilities.rcon_servers. Regex рассчитан на строки с именем карты .bsp; проверьте реальный вывод в панели. Целевая команда здесь только выводит выбранное значение, не меняет карту сервера.

## Ответы, ошибки и проверка проблем

Форма ответа зависит от операции: команды используют data / total / limit / offset, модули — data, интеграции — providers / accounts, аналитика — свои поля. Не считайте data универсальной оболочкой. Изменения обычно возвращают success: true; при ошибке читайте error и, если есть, issues или code вместе с HTTP-статусом.
- 400: неверный JSON, поля, ID, regex или неподдерживаемый модуль. Исправьте запрос.
- 401: ключ отсутствует или неверен; у usage — нет сессии панели.
- 403: ключ выключен, IP запрещён, scope/право отсутствует, интеграция скрыта (code HIDDEN) или нужен тариф (code PLAN). Сверьте ключ и каталог интеграций.
- 404: объект не найден в чате ключа. Получите ID/имя через чтение этого же чата.
- 405: метод не поддерживается. Смотрите каталог ниже и заголовок Allow.
- 409: кастомная команда уже существует. Проверьте её и при необходимости используйте PUT.
- 413: тело слишком большое. Сократите запрос; у каждой операции свой предел.
- 429: исчерпана квота или ограничена частота. Прекратите частые повторы, проверьте лимиты в панели.
- 5xx или таймаут: сохраните время, метод, путь и текст ошибки без ключей. Чтение повторяйте ограниченно, увеличивая задержку; перед повторной записью проверьте фактическое состояние. Не повторяйте POST после таймаута вслепую.

Если бот молчит: проверьте чат, enabled команды и модуля, allow_standard_commands / allow_generator_commands, cooldown, ранг участника и права бота на платформе. Если нет статистики: доступность БД, таблицу/поля, активность источника и привязку игрока. Если нет интеграционных событий: enabled, hasSecret, lastError, lastSyncAt, тариф и работающий воркер. Наличие настройки в GET не гарантирует внешнее событие.

## Точность истории
В отчётах панели активность чатов и технические метрики сохраняют исходное время 14 дней; от 14 до 30 дней используются часовые сводки, старше 30 дней — интервалы 3 часа (UTC). Счётчики сообщений и суммы измерений сохраняются, средние взвешены по числу измерений. Сводки активности и метрик хранятся 180 дней, сводки мониторинга серверов — 730 дней. Тексты сообщений, платежи и операции казны не объединяются в эти сводки. Историю, удалённую прежней политикой хранения, восстановить из сводок нельзя.

## Полный каталог методов

read / write — требуемое право операции; public — ключ не нужен. Перечень полей — краткая подсказка, не полная JSON Schema. Подробные правила и различия сохранения описаны выше.

- `GET /api/v1` (public): Каталог публичного API.
- `GET /api/v1/commands` (read, scope=commands): Список стандартных, кастомных и RCON команд с флагом enabled.
  Query: `kind` — all / standard / custom / rcon / active; `limit` — Кол-во; `offset` — Смещение; `command` — Точное имя кастомной команды: вернуть полную конфигурацию для PUT вместо списка.
- `PATCH /api/v1/commands` (write, scope=commands): Включить или выключить команду.
  JSON: `command` — Имя команды; `enabled` — true / false; `show_in_list` — true / false, необязательно; `kind` — standard / custom / rcon, необязательно.
- `GET /api/v1/modules` (read, scope=settings): Список модулей чата и их состояние.
- `PATCH /api/v1/modules` (write, scope=settings): Включить или выключить модуль.
  JSON: `module` — Код модуля, например clans; `enabled` — true / false.
- `GET /api/v1/modules/top` (read, scope=analytics): Топ модуля (кланы, репутация, уровни и др.).
  Query: `module` — Код модуля; `limit` — Размер топа.
- `GET /api/v1/modules/users` (read, scope=analytics): Пользователи модуля.
  Query: `module` — Код модуля; `limit` — Кол-во; `page` — Страница; `search` — Поиск по имени.
- `GET /api/v1/analytics` (read, scope=analytics): Сводка: пользователи, команды, активность, топы.
  Query: `period` — 1d, 7d, 30d, 90d.
- `GET /api/v1/analytics/commands` (read, scope=analytics): Использование команд за период.
  Query: `period` — 1d, 7d, 30d, 90d; `limit` — Топ команд.
- `GET /api/v1/analytics/activity` (read, scope=analytics): Ежедневная активность чата.
  Query: `period` — 1d, 7d, 30d, 90d.
- `GET /api/v1/stats` (read, scope=analytics): Серверы мониторинга, топ сессий и топ kills из внешней БД статистики.
  Query: `period` — 1d, 7d, 30d, 90d; `limit` — Топ игроков.
- `GET /api/v1/logs` (read, scope=analytics): Журнал команд, модерации или админки.
  Query: `type` — commands / moderation / admin; `period` — 1d, 7d, 30d, 90d, all; `limit` — Кол-во; `offset` — Смещение.
- `GET /api/v1/usage` (сессия панели, query chatId обязателен; API-ключ не заменяет сессию): Использование API-ключей чата.
- `GET /api/v1/usage/history` (сессия панели, query chatId обязателен; API-ключ не заменяет сессию): История запросов API по дням.
  Query: `days` — 1–30.
- `GET /api/v1/variables` (read, scope=analytics): Переменные чата.
- `PUT /api/v1/variables` (write, scope=analytics): Изменить существующую переменную.
  JSON: `name` — Имя переменной; `value` — Значение.
- `GET /api/v1/settings` (read, scope=settings): Настройки чата и счётчик команд.
- `PATCH /api/v1/settings` (write, scope=settings): Изменить базовые настройки чата.
  JSON: `language` — ru / en; `global_cooldown` — Секунды, 0–300; `max_commands_per_minute` — 0–60; `allow_standard_commands` — true / false; `allow_generator_commands` — true / false; `buttons_enabled` — true / false.
- `GET /api/v1/welcome` (read, scope=welcome): Настройки приветствия.
- `PATCH /api/v1/welcome` (write, scope=welcome): Включить, выключить или изменить welcome.
  JSON: `is_enabled` — true / false; `message_text` — Текст, необязательно; `use_name` — true / false, необязательно.
- `GET /api/v1/farewell` (read, scope=farewell): Настройки прощания.
- `PATCH /api/v1/farewell` (write, scope=farewell): Включить, выключить или изменить farewell.
  JSON: `is_enabled` — true / false; `message_text` — Текст, необязательно; `use_name` — true / false, необязательно.
- `GET /api/v1/members` (read, scope=members): Участники чата.
  Query: `limit` — Кол-во; `offset` — Смещение; `search` — Поиск.
- `GET /api/v1/users` (read, scope=members): Пользователи и ники статистики.
  Query: `limit` — Кол-во; `offset` — Смещение; `search` — Поиск; `platform` — vk / tg / ds.
- `GET /api/v1/profile` (read, scope=members): Публичный профиль участника.
  Query: `platform` — vk / tg / ds; `user_id` — ID пользователя.
- `GET /api/v1/nicknames` (read, scope=nicknames): Список ников.
  Query: `limit` — Кол-во записей; `offset` — Смещение; `search` — Поиск по нику.
- `GET /api/v1/ranks` (read, scope=ranks): Ранги и пользователи с рангами.
- `POST /api/v1/ranks` (write, scope=ranks): Назначить или снять ранг.
  JSON: `platform` — vk / telegram / discord; `platformUserId` — ID пользователя; `rankId` — ID ранга; `action` — revoke — снять ранг.
- `GET /api/v1/moderation` (read, scope=moderation): Активные муты и баны.
  Query: `type` — mute / ban, необязательно; `limit` — Кол-во; `offset` — Смещение.
- `GET /api/v1/punishments` (read, scope=moderation): История наказаний.
  Query: `type` — mute / ban / warn / kick; `limit` — Кол-во; `offset` — Смещение.
- `GET /api/v1/automod` (read, scope=moderation): Правила автомодерации.
- `PATCH /api/v1/automod` (write, scope=moderation): Включить или выключить правило автомода.
  JSON: `ruleId` — ID правила; `enabled` — true / false.
- `GET /api/v1/capabilities` (read): Что можно делать этим ключом: тариф, модули ключа, эндпоинты и имена команд без выгрузки БД.
- `GET /api/v1/integrations` (read, scope=integrations): Каталог интеграций и настройки текущего чата без секретов.
- `PATCH /api/v1/integrations` (write, scope=integrations): Включить интеграцию и сохранить config/secret.
  JSON: `provider` — steam / donationalerts / yoomoney / twitch / vkdonut / sourcebans / faceit; `enabled` — true / false; `secret` — Секрет провайдера, необязательно если уже сохранён; `config` — JSON настроек провайдера.
- `POST /api/v1/commands` (write, scope=commands): Создать кастомную команду.
  JSON: `com` — Имя кастомной команды, до 64 символов; `vorker` — Ответ, 1–4096 символов; подстановки и текст; `description` — Описание команды; `category` — Категория, до 50 символов; `cooldown` — Пауза 0–3600 секунд; `required_rank` — ID ранга этого чата; 0 — без ограничения; `role_ids` — Массив ID рангов, до 20; `rank_group_ids` — Массив ID групп рангов, до 20; `custom` — Объект: ip, game_type, response_format, изображения и настройки ответа; `buttons` — До 25 кнопок: label, action (command/link/text), value, row (0–4), color; `status` — 0/1, доступность команды; `show_in_list` — 0/1, показывать в списке; `alias_for` — Имя команды-алиаса или null в JSON; `deny_action` — message / silent / custom при отсутствии прав; `deny_message` — Сообщение при deny_action=custom; `button_response_mode` — edit / new: обновить сообщение или отправить новое.
- `PUT /api/v1/commands` (write, scope=commands): Изменить кастомную команду.
  JSON: `com` — Имя кастомной команды, до 64 символов; `vorker` — Ответ, 1–4096 символов; подстановки и текст; `description` — Описание команды; `category` — Категория, до 50 символов; `cooldown` — Пауза 0–3600 секунд; `required_rank` — ID ранга этого чата; 0 — без ограничения; `role_ids` — Массив ID рангов, до 20; `rank_group_ids` — Массив ID групп рангов, до 20; `custom` — Объект: ip, game_type, response_format, изображения и настройки ответа; `buttons` — До 25 кнопок: label, action (command/link/text), value, row (0–4), color; `status` — 0/1, доступность команды; `show_in_list` — 0/1, показывать в списке; `alias_for` — Имя команды-алиаса или null в JSON; `deny_action` — message / silent / custom при отсутствии прав; `deny_message` — Сообщение при deny_action=custom; `button_response_mode` — edit / new: обновить сообщение или отправить новое; `originalCom` — Старое имя при переименовании; PUT сохраняет всю конфигурацию.
- `GET /api/v1/rcon` (read, scope=commands): RCON-команды без паролей серверов.
- `PATCH /api/v1/rcon` (write, scope=commands): Включить или выключить RCON-команду.
  JSON: `command` — Имя команды; `enabled` — true / false.
- `GET /api/v1/auto-buttons` (read, scope=commands): Автокнопки RCON без кэша и секретов.
- `POST /api/v1/auto-buttons` (write, scope=commands): Создать автокнопки; можно создать команду-источник.
  JSON: `name` — Название; `source_command` — RCON-шаблон, например status; `button_command` — Команда кнопки с {value}; `ensure_source` — true — создать команду-источник; `source_rcon_server_id` — ID RCON-сервера из capabilities; `source_rcon_command_id` — ID команды-источника из GET /rcon; `ensure_target` — Создать простую целевую команду, если её нет; RCON-цель сначала создайте через POST /rcon; `parse_mode` — simple / advanced; `line_regex` — Фильтр строки и захват значения; `line_extract_group` — Группа захвата 0–20; обычно 1; `button_label_template` — Текст кнопки с {value}; `max_buttons` — 1–50; `cache_ttl` — Кэш значений 0–86400 секунд.
- `PUT /api/v1/auto-buttons` (write, scope=commands): Изменить автокнопки.
  JSON: `id` — ID конфигурации; `name` — Название.
- `GET /api/v1/formats` (read, scope=settings): Переопределения data и системные образцы defaults с ключами и подстановками.
- `PATCH /api/v1/formats` (write, scope=settings): Записать одно поле формата.
  JSON: `command_type` — Тип, например rcon; `format_key` — Ключ формата; `format_value` — Значение; `is_enabled` — Включить или выключить переопределение; необязательно.
- `GET /api/v1/stats-servers` (read, scope=settings): Серверы статистики без паролей БД.
- `PATCH /api/v1/stats-servers` (write, scope=settings): Включить или выключить сервер статистики.
  JSON: `id` — ID сервера; `is_active` — true / false.
- `GET /api/v1/images` (read, scope=commands): Картинки кастомных команд (только URL).
- `PATCH /api/v1/images` (write, scope=commands): Заменить список картинок команды.
  JSON: `command` — Имя команды; `images` — JSON-массив URL.
- `POST /api/v1/rcon` (write, scope=commands): Создать RCON-команду с параметрами, правами и шаблоном ответа.
  JSON: `rcon_server_id` — ID RCON-сервера чата из capabilities.rcon_servers; `command_name` — Имя команды в чате, до 64 символов; `rcon_template` — Команда сервера, например changelevel {1}; до 512 символов; `description` — Описание, до 255 символов; `required_rank` — ID разрешённого ранга; для управления сервером задайте администраторский; `params_schema` — Массив {name,label,required}; значения подставляются по порядку как {1}, {2} и т.д.; `cooldown` — 0–86400 секунд; `response_template` — Ответ с {response}, {lines}, {line_count}; до 2048 символов; `response_rules` — До 5 правил {regex,template,buttons}; до 3 кнопок в правиле; `show_in_list` — 0/1.
- `PUT /api/v1/rcon` (write, scope=commands): Изменить RCON-команду по id; пропущенные поля сохраняются.
  JSON: `id` — ID команды из GET /rcon; `rcon_server_id` — ID RCON-сервера чата из capabilities.rcon_servers; `command_name` — Имя команды в чате, до 64 символов; `rcon_template` — Команда сервера, например changelevel {1}; до 512 символов; `description` — Описание, до 255 символов; `required_rank` — ID разрешённого ранга; для управления сервером задайте администраторский; `params_schema` — Массив {name,label,required}; значения подставляются по порядку как {1}, {2} и т.д.; `cooldown` — 0–86400 секунд; `response_template` — Ответ с {response}, {lines}, {line_count}; до 2048 символов; `response_rules` — До 5 правил {regex,template,buttons}; до 3 кнопок в правиле; `show_in_list` — 0/1; `is_enabled` — Включена ли команда.
- `DELETE /api/v1/rcon` (write, scope=commands): Удалить RCON-команду по id.
  JSON: `id` — ID команды; JSON-тело запроса.
- `POST /api/v1/variables` (write, scope=analytics): Создать переменную для ответа (платный тариф, до 50 на чат).
  JSON: `name` — 1–50 букв, цифр и _, кроме системных имён; `value` — Текст до 2000 символов; подстановка |имя|; `description` — Описание, до 255 символов.
- `GET /api/v1/stats-commands` (read, scope=commands): Полные настройки команд игровой статистики.
- `POST /api/v1/stats-commands` (write, scope=commands): Создать команду статистики с топом, формулой и кнопками.
  JSON: `stats_server_id` — ID существующего источника из GET /stats-servers; `command_name` — Имя команды в чате; `command_type` — top / player_stats / server_info / server_online / custom; `template` — Шаблон ответа до 2048 символов; `response_format` — detailed / list / compact / custom; `top_limit` — 1–50, по умолчанию 10; `sort_field` — Поле источника, например kills; `sort_order` — ASC / DESC; `sort_type` — Дополнительный тип сортировки, обычно пустая строка; `score_formula` — Формула для top, например kills / max(deaths, 1); null отключает; `score_label` — Подпись вычисленного рейтинга; `required_rank` — ID ранга этого чата; 0 — без ограничения; `cooldown` — 0–86400 секунд; `description` — Описание команды; `buttons` — До 10 кнопок {label,action:command/link,value}; `notify_mentions` — Уведомлять упомянутых пользователей; `is_enabled` — Включена ли команда; `show_in_list` — Видна ли в списке команд.
- `PUT /api/v1/stats-commands` (write, scope=commands): Изменить команду статистики по id; пропущенные поля сохраняются.
  JSON: `id` — ID команды из GET /stats-commands; `stats_server_id` — ID существующего источника из GET /stats-servers; `command_name` — Имя команды в чате; `command_type` — top / player_stats / server_info / server_online / custom; `template` — Шаблон ответа до 2048 символов; `response_format` — detailed / list / compact / custom; `top_limit` — 1–50, по умолчанию 10; `sort_field` — Поле источника, например kills; `sort_order` — ASC / DESC; `sort_type` — Дополнительный тип сортировки, обычно пустая строка; `score_formula` — Формула для top, например kills / max(deaths, 1); null отключает; `score_label` — Подпись вычисленного рейтинга; `required_rank` — ID ранга этого чата; 0 — без ограничения; `cooldown` — 0–86400 секунд; `description` — Описание команды; `buttons` — До 10 кнопок {label,action:command/link,value}; `notify_mentions` — Уведомлять упомянутых пользователей; `is_enabled` — Включена ли команда; `show_in_list` — Видна ли в списке команд.
- `DELETE /api/v1/stats-commands` (write, scope=commands): Удалить команду статистики (JSON {id}).
  JSON: `id` — ID команды из GET /stats-commands.

Для конкретного чата источники истины — ответы capabilities, modules, integrations, настройки панели и фактическая проверка команды. Не придумывайте отсутствующие эндпоинты, ID, имена таблиц, секреты и доступные тарифу функции.