{ "openapi": "3.0.3", "info": { "title": "API BotHunter", "version": "2.0", "description": "Внешний API BotHunter позволяет работать со своими сообществами из собственного кода: с ботами, рассылками, списками, контактами, переменными, лендингами, воронками, статистикой и сотрудниками. На этом же API работает MCP BotHunter (`https://mcp.bothunter.ai/mcp`).\n\nКаждый метод вызывается по своему адресу: `https://bot-api.targethunter.ru/external-api/v2/{раздел}/{метод}`. Актуальная версия API — v2. Все примеры и описания в справке — для v2. Отправляйте запросы методом `POST`, а параметры передавайте в теле запроса в формате JSON. Параметры можно передать и как форму или в строке запроса — это тоже работает. Параметры, имя которых начинается с `_`, служебные: сервер их не принимает.\n\n## Быстрый старт\n\n1. Получите личный токен. Токен — это длинная строка, которая заменяет логин и пароль: по ней API понимает, что запрос отправили вы. Откройте страницу [«Доступы и токены»](https://targethunter.ru/settings/access), выпустите токен и выберите для него продукт BotHunter. Срок действия выбирается при выпуске: 30 дней, 1 год или без срока — для постоянной интеграции берите «без срока». Токен целиком показывается только один раз — сразу скопируйте его и сохраните.\n2. Проверьте токен методом `users/me`. Подставьте свой токен вместо `<ваш_токен>`:\n\n```bash\ncurl -X POST https://bot-api.targethunter.ru/external-api/v2/users/me \\\n -H \"Authorization: Bearer <ваш_токен>\"\n```\n\n Если всё в порядке, в ответе придёт `\"status\": \"ok\"` и ваш номер пользователя TargetHunter в поле `user_id`. Если пришла ошибка 4, токен не подошёл. Проверьте, что скопировали его целиком и выбрали у него продукт BotHunter. Если токен истёк или его отозвали, выпустите новый.\n\n3. Получите список сообществ методом `groups/get`:\n\n```bash\ncurl -X POST https://bot-api.targethunter.ru/external-api/v2/groups/get \\\n -H \"Authorization: Bearer <ваш_токен>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"count\": 10}'\n```\n\n В ответе придёт массив `items`. У каждого сообщества есть `group_id`, `channel` и название `name`. Запомните `group_id` и `channel` нужного сообщества: их просят почти все остальные методы.\n\nНесколько понятий, которые встречаются почти во всех методах:\n\n- **Сообщество и канал.** Канал — это соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Сообщество задают два параметра: `group_id` — номер сообщества в этом канале и `channel` — сам канал. Передавайте их вместе: номера сообществ в разных каналах могут совпадать. Оба значения есть в ответе `groups/get`. Канал можно писать и маленькими буквами.\n- **Подписчик.** Человека в сообществе задают параметром `uid` — это его номер в соцсети или мессенджере, например id страницы ВКонтакте.\n- **ID ботов, списков, рассылок и других объектов** — строка из 24 символов: цифры и буквы от a до f, например `65a6e5f4c0e8f20012d3a111`. В запросе такой ID передают в параметре с именем объекта: `bot_id`, `list_id`, `var_id`, `mailing_id` и других. В ответе он лежит в поле `id`. Берите ID из ответов методов, которые возвращают списки: например, `bot_id` — это `id` из ответа `bots/get`.\n- **Даты.** В запросе дату пишут строкой `dd.mm.yyyy hh:ii` по московскому времени, например `01.09.2026 18:30`. В ответе время приходит как unix-время — число секунд, прошедших с 1 января 1970 года: например, `1735689600` — это 1 января 2025 года, 00:00 по Гринвичу. Исключение — методы `stats/*`: у них даты в ответах приходят строками.\n- **Списки и страницы.** Методы, которые возвращают много записей, отвечают так: `{\"items\": [...], \"total\": N}`. В `items` — записи, в `total` — сколько их всего. За один запрос приходит одна страница. Её задают два параметра: `count` — сколько записей вернуть (по умолчанию 100, не больше 500) и `offset` — сколько записей пропустить от начала. Например, первая страница по 100 записей — `offset=0`, вторая — `offset=100`, третья — `offset=200`. Новые записи идут первыми, если у метода не сказано иначе.\n\n## Версии\n\nАктуальная версия API — v2. Все примеры и описания в справке — для v2. Прежний адрес без версии (`/external-api/…`) работает для старых интеграций, для новых используйте v2. От v2 он отличается только мелочами в методах `stats/*`. Если указать в адресе другую версию, например `v3`, придёт ошибка 1.\n\n## Вход\n\nКаждый запрос должен показать, от чьего имени он отправлен. Для этого есть два способа.\n\n- **`Authorization: Bearer <токен>`** — основной способ: токен передают в заголовке запроса. Подойдёт личный токен со страницы [«Доступы и токены»](https://targethunter.ru/settings/access) с продуктом BotHunter или токен приложения, которому вы разрешили доступ к BotHunter (например, MCP BotHunter). С токеном доступны ваши сообщества и те, где вам выдали роль сотрудника. Если токен выпущен для другого продукта, придёт ошибка 4.\n- **`api_key`** — параметр запроса. Он нужен там, где свой заголовок задать нельзя. В нём можно передать:\n - тот же токен TargetHunter, что и в заголовке, — он начинается с `thp_`, `lhp_` или `tha_`. Так подключают инструменты без своих заголовков: например, «Вызвать URL» в GetCourse или вебхуки форм. Для таких интеграций выпустите отдельный токен только с продуктом BotHunter: адрес с токеном сохраняется в журналах сервиса, который его вызывает, а отдельный токен можно отозвать, не трогая остальные интеграции;\n - прежний ключ со страницы [настроек TargetHunter](https://targethunter.ru/settings) (блок «Токен доступа») в v2 не принимается: придёт ошибка 4. Он работает только с прежним адресом без версии (v1).\n\n Если можете, передавайте `api_key` в теле запроса: в JSON или в форме. В строке запроса (`?api_key=…`) он тоже работает, но тогда адрес запроса вместе с токеном или ключом сохраняется в журналах серверов.\n\nЕсли переданы и заголовок, и `api_key`, используется заголовок. Сервер запоминает проверку токена на минуту, поэтому отозванный токен может работать ещё до 60 секунд.\n\n## Доступ сотрудников\n\nКроме владельца, с сообществом могут работать сотрудники. Роль сотрудника — это набор прав, который выдают сотруднику в интерфейсе BotHunter. Владельцу сообщества и сотруднику с ролью «Админ (полный доступ)» доступны все методы. Остальным сотрудникам раздел API открывает та же роль, что и такой же раздел в интерфейсе. Роль действует только в своём канале.\n\n| Методы | Роль сотрудника |\n|---|---|\n| `bots/*`, `mailings/*`, `attachments/*`, `stats/getMailingsStats`, `stats/getMailingStats` | «Рассылки и чат-боты» |\n| `contacts/*`, `lists/*`, `vars/*`, `globalVars/*` | «Пользователи» |\n| `stats/getLandingsStats`, `stats/getLandingStats`, `stats/getAdsSubscribes` | «Статистика» |\n| `groups/getEmployees` | только «Админ (полный доступ)» |\n| `funnels/*`, `landings/*` | любая роль |\n\nЕсли у сотрудника нет нужной роли, придёт ошибка 8 «У вас нет доступа для управления этим объектом». `bots/get` без `group_id` и `stats/getAdsSubscribes` ищут только в тех сообществах, где нужный раздел вам открыт. `groups/get` показывает все сообщества, где у вас есть хоть какая-то роль.\n\n## Ответ и ошибки\n\nСервер всегда отвечает с HTTP-кодом 200 — даже при ошибке. Удался ли запрос, видно по полю `status`.\n\nУспешный ответ — `{\"status\": \"ok\", \"response\": …}`, данные лежат в `response`. У методов, которые выполняют действие и ничего не возвращают (`bots/addUser`, `lists/addUser`, `vars/set` и другие), поля `response` нет: ответ — просто `{\"status\": \"ok\"}`.\n\nОтвет с ошибкой — `{\"status\": \"error\", \"error\": \"описание\", \"error_code\": 7}`. В `error` — текст ошибки, в `error_code` — её номер из таблицы:\n\n| Код | Что значит |\n|---|---|\n| `1` | Не указан раздел или метод, такого раздела нет или в адресе неизвестная версия |\n| `3` | В разделе нет такого метода |\n| `4` | Токен или ключ не передан или не подходит: токен истёк, отозван или выпущен не для BotHunter |\n| `5` | Слишком много запросов — больше 30 в секунду, или слишком много созданий — больше 20 в минуту или 200 в сутки |\n| `6` | Метод не смог выполнить действие — причина в поле `error` |\n| `7` | Не передан обязательный параметр или он неверный, или объект с таким ID не найден. Если объект принадлежит чужому сообществу, ответ такой же, как если бы его не было: ошибка 7 |\n| `8` | Нет доступа к сообществу или разделу: вы не владелец и не сотрудник сообщества или у вас нет нужной роли |\n| `9` | Сервис проверки ключа временно недоступен — повторите запрос чуть позже |\n| `101` | Внутренняя ошибка сервера |\n\nМожно отправлять не больше 30 запросов в секунду. При входе по токену лимит считается на пользователя — на все его токены вместе. Если запросов больше, придёт ошибка 5: подождите немного и повторите запрос.\n\nОтдельный лимит — на создание. Методы `lists/create`, `vars/create` и `globalVars/create` вместе можно вызвать не больше 20 раз в минуту и 200 раз в сутки. Лимит считается на пользователя TargetHunter — на все его токены и ключи вместе. Считается каждая попытка в сообществе, к которому у вас есть доступ, даже с ошибкой в параметрах. Счётчик за минуту обнуляется в начале каждой минуты, счётчик за сутки — в 03:00 по московскому времени. Если лимит исчерпан, придёт ошибка 5 и ничего не создастся. На `lists/rename` этот лимит не действует." }, "servers": [ { "url": "https://bot-api.targethunter.ru/external-api/v2", "description": "BotHunter" } ], "security": [ { "bearerAuth": [] }, { "apiKey": [] } ], "tags": [ { "name": "Аккаунт", "description": "`users/me` — проверить токен: кому он принадлежит и как выполнен вход." }, { "name": "Сообщества", "description": "Методы `groups/*`: сообщества, с которыми можно работать, и их сотрудники. Номер сообщества `group_id` и канал `channel` из ответа `groups/get` нужны почти всем остальным методам. `groups/getEmployees` доступен только владельцу и сотрудникам с ролью «Админ (полный доступ)»." }, { "name": "Боты", "description": "Методы `bots/*`: список ботов и их шагов, включение и выключение бота, запуск и остановка бота для подписчика. Сотруднику нужна роль «Рассылки и чат-боты»." }, { "name": "Рассылки", "description": "Методы `mailings/*` только читают рассылки сообщества: весь список или одну рассылку подробно. `attachments/getById` даёт ссылку на файл вложения рассылки. Сотруднику нужна роль «Рассылки и чат-боты»." }, { "name": "Списки", "description": "Методы `lists/*` работают с обычными списками подписчиков: можно посмотреть списки и их подписчиков, создать и переименовать список, добавить подписчика в список или убрать из него. Чёрного списка в этих методах нет. Сотруднику нужна роль «Пользователи»." }, { "name": "Контакты", "description": "Методы `contacts/*`: всё об одном подписчике — карточка, значения переменных, списки и боты, в которых он сейчас. Сотруднику нужна роль «Пользователи»." }, { "name": "Пользовательские переменные", "description": "Методы `vars/*` работают с переменными, у которых у каждого подписчика своё значение: например, город или число бонусов. Можно создать переменную, прочитать, записать и очистить её значение у подписчика. Сотруднику нужна роль «Пользователи»." }, { "name": "Переменные сообщества", "description": "Методы `globalVars/*` работают с переменными, у которых одно значение на всё сообщество: например, промокод недели. Можно создать переменную, прочитать, записать и очистить её значение. Сотруднику нужна роль «Пользователи»." }, { "name": "Лендинги", "description": "`landings/get` — мини-лендинги и мультиканальные лендинги сообщества. Сотруднику подойдёт любая роль." }, { "name": "Воронки", "description": "Методы `funnels/*`: воронки сообщества и статистика по их шагам. Сотруднику подойдёт любая роль." }, { "name": "Статистика", "description": "Методы `stats/*`: статистика рассылок (нужна роль «Рассылки и чат-боты»), лендингов и рекламных меток (нужна роль «Статистика»). Даты в ответах этого раздела приходят строками, а не unix-временем." } ], "paths": { "/users/me": { "post": { "tags": [ "Аккаунт" ], "operationId": "usersMe", "summary": "Проверить токен", "description": "Показывает, кому принадлежит токен или ключ и как выполнен вход. Вызовите этот метод первым: если он ответил без ошибки, токен работает.\n\nПараметров нет. Если передаёте токен в параметре `api_key`, передайте только его.\n\nВ ответе `user_id` — ваш номер пользователя в TargetHunter, `auth` — способ входа, `client_id` — кому выдан токен.\n\n**Кому доступен:** любому действующему токену или ключу, роль сотрудника не нужна.\n\n**Ошибки метода:**\n- `4` — «Токен недействителен», «API ключ недействителен» или «Не указан ключ API». Проверьте, что скопировали токен целиком и выбрали у него продукт BotHunter. Если токен истёк или его отозвали, выпустите новый.\n- `9` — сервис проверки ключа временно недоступен. Повторите запрос чуть позже.", "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/Me" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "user_id": 123456, "auth": "bearer", "client_id": "personal" } } }, "error": { "summary": "Ошибка 4", "value": { "status": "error", "error": "Токен недействителен", "error_code": 4 } } } } } } } } }, "/groups/get": { "post": { "tags": [ "Сообщества" ], "operationId": "groupsGet", "summary": "Список сообществ", "description": "Показывает сообщества, с которыми вы можете работать: ваши собственные и те, где вы сотрудник с любой ролью. Сообщества из всех каналов приходят одним списком, в том числе разложенные по папкам в интерфейсе. Сначала идут подключённые последними.\n\nОбычно это второй вызов после `users/me`. Из ответа возьмите `group_id` и `channel` нужного сообщества — их просят почти все остальные методы. `group_id` — номер сообщества в соцсети или мессенджере, `channel` — где работает сообщество: `VK`, `TG`, `OK`, `MAX`, `CHAT` или `AVITO`.\n\nПоле `archived` показывает, что сообщество в архиве, `deactivated` — что оно отключено в BotHunter. В таких сообществах лучше ничего не менять.\n\n**Кому доступен:** любому действующему токену или ключу, роль сотрудника не нужна.\n\n**Ошибки метода:**\n- `7` — «Указан неверный канал»: в `channel` значение не из списка.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Показать сообщества только из одного канала: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито.", "example": "VK" }, "search": { "type": "string", "description": "Часть названия сообщества. Большие и маленькие буквы не различаются. Работает как поиск в списке сообществ в интерфейсе.", "example": "кофейня" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } } }, "example": { "channel": "VK", "count": 10 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "group_id": 123456, "channel": "VK", "name": "Моё сообщество", "photo": "https://sun1-1.userapi.com/photo.jpg", "is_owner": true, "archived": false, "deactivated": false } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Указан неверный канал", "error_code": 7 } } } } } } } } }, "/groups/getEmployees": { "post": { "tags": [ "Сообщества" ], "operationId": "groupsGetEmployees", "summary": "Сотрудники сообщества", "description": "Показывает сотрудников сообщества и их роли — то же, что раздел «Сотрудники» в интерфейсе. Метод только читает: добавить или удалить сотрудника через него нельзя. Сначала идут добавленные последними.\n\nВладелец сообщества сотрудником не считается и в список не входит.\n\nУ каждой роли в `roles` два поля: `key` — постоянный ключ роли и `title` — её название, как в интерфейсе. Проверяйте роли по `key`: название может поменяться, а ключ — нет.\n\n| `key` | `title` |\n|---|---|\n| `admin` | Админ (полный доступ) |\n| `mailer` | Рассылки и чат-боты |\n| `users` | Пользователи |\n| `integrations` | Управление интеграциями |\n| `stat` | Статистика |\n| `event` | События |\n| `dogs` | Удаление заблокированных участников |\n| `crm` | Диалоги |\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец сообщества и у вас нет роли «Админ (полный доступ)».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": 123456, "name": "Анна Смирнова", "roles": [ { "key": "mailer", "title": "Рассылки и чат-боты" }, { "key": "stat", "title": "Статистика" } ] } ], "total": 1 } } }, "error": { "summary": "Ошибка 8", "value": { "status": "error", "error": "У вас нет доступа для управления этим объектом", "error_code": 8 } } } } } } } } }, "/bots/get": { "post": { "tags": [ "Боты" ], "operationId": "botsGet", "summary": "Список ботов", "description": "Показывает ботов. Без параметров — ботов всех сообществ, где вам открыт раздел ботов. Сначала идут новые.\n\nЧтобы получить ботов одного сообщества, передайте `group_id` и `channel`. Отобрать ботов можно ещё по состоянию (`active`), архиву (`archived`) и названию (`search`).\n\nНомера сообществ в разных каналах могут совпадать: например, сообщество ВКонтакте и канал Telegram с одинаковым `group_id`. Если вы передали `group_id` без `channel`, а у вас есть сообщества с этим номером в нескольких каналах, придёт ошибка 7 с просьбой указать `channel`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — сообщество не найдено; неверное значение `group_id`, `channel`, `active` или `archived`; сообщество с таким `group_id` есть в нескольких каналах — добавьте `channel`.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Рассылки и чат-боты».", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества — `group_id` из ответа `groups/get`. Если передать, вернутся только боты этого сообщества. Без него — боты всех сообществ, где вам открыт раздел ботов.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть или мессенджер: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Если передать, вернутся только боты из этого канала.", "example": "VK" }, "active": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` — только включённые боты, `0` — только выключенные." }, "archived": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` — только боты в архиве, `0` — только боты не в архиве." }, "search": { "type": "string", "description": "Часть названия бота. Большие и маленькие буквы не различаются.", "example": "запись" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } } }, "example": { "group_id": 123456, "channel": "VK", "active": 1, "count": 20 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "607d97c6a01c6a25972ed95e", "name": "Мой бот", "group_id": 123456, "channel": "VK", "active": 1, "archived": 0, "activity_type": "message_new", "create_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Группа не найдена или нет доступа", "error_code": 7 } } } } } } } } }, "/bots/getById": { "post": { "tags": [ "Боты" ], "operationId": "botsGetById", "summary": "Подробно об одном боте", "description": "Показывает одного бота по его ID. В ответе те же поля, что в `bots/get`, и ещё несколько: например, можно ли передать бота как шаблон и какие мини-лендинги его запускают.\n\nID бота — строка из 24 символов. Её берут из поля `id` в ответе `bots/get`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Бот не найден»: бота с таким `bot_id` нет или он из чужого сообщества. Та же ошибка, если `bot_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID бота — строка из 24 символов. Возьмите поле `id` из ответа `bots/get`.", "example": "607d97c6a01c6a25972ed95e" } }, "required": [ "bot_id" ] }, "example": { "bot_id": "607d97c6a01c6a25972ed95e" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/BotDetails" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "607d97c6a01c6a25972ed95e", "name": "Мой бот", "group_id": 123456, "channel": "VK", "active": 1, "archived": 0, "activity_type": "message_new", "create_at": 1704067200, "public_id": null, "can_share": false, "is_favorite": false, "time_archived": 0, "activity_param": null, "subscription_ids": [] } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Бот не найден", "error_code": 7 } } } } } } } } }, "/bots/getSteps": { "post": { "tags": [ "Боты" ], "operationId": "botsGetSteps", "summary": "Шаги бота", "description": "Показывает шаги бота — те же, что в списке выбора шага в интерфейсе. Сначала идут новые.\n\nМетод нужен, чтобы узнать `step_id` для `bots/addUser`, то есть с какого шага запустить бота для человека.\n\nСтартовый шаг отмечен полем `is_start`. С него `bots/addUser` начинает, если `step_id` не передан.\n\nЗаметки на холсте бота в список не входят: это не шаги сценария.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Бот не найден»: бота с таким `bot_id` нет или он из чужого сообщества. Та же ошибка, если `bot_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID бота — строка из 24 символов. Возьмите поле `id` из ответа `bots/get`.", "example": "607d97c6a01c6a25972ed95e" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "bot_id" ] }, "example": { "bot_id": "607d97c6a01c6a25972ed95e" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BotStep" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "607d97c6a01c6a25972ed960", "title": "Приветствие", "contain": "messages", "contain_name": "Сообщение", "is_start": false }, { "id": "607d97c6a01c6a25972ed95f", "title": "Получено новое входящее сообщение", "contain": null, "contain_name": null, "is_start": true } ], "total": 2 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Бот не найден", "error_code": 7 } } } } } } } } }, "/bots/enable": { "post": { "tags": [ "Боты" ], "operationId": "botsEnable", "summary": "Включить бота", "description": "Включает бота. Если бот был в архиве, метод заодно достаёт его оттуда. В ответе — бот в том же виде, что в `bots/get`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Бот не найден»: бота с таким `bot_id` нет или он из чужого сообщества. Та же ошибка, если `bot_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».\n- `8` — сообщество находится в архиве.\n- `6` — бота нельзя включить. Например, удалён мини-лендинг, подписка на который запускает этого бота.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID бота — строка из 24 символов. Возьмите поле `id` из ответа `bots/get`.", "example": "607d97c6a01c6a25972ed95e" } }, "required": [ "bot_id" ] }, "example": { "bot_id": "607d97c6a01c6a25972ed95e" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/Bot" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "607d97c6a01c6a25972ed95e", "name": "Мой бот", "group_id": 123456, "channel": "VK", "active": 1, "archived": 0, "activity_type": "message_new", "create_at": 1704067200 } } }, "error": { "summary": "Ошибка 8", "value": { "status": "error", "error": "Сообщество находится в архиве", "error_code": 8 } } } } } } } } }, "/bots/disable": { "post": { "tags": [ "Боты" ], "operationId": "botsDisable", "summary": "Выключить бота", "description": "Выключает бота. В ответе — бот в том же виде, что в `bots/get`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Бот не найден»: бота с таким `bot_id` нет или он из чужого сообщества. Та же ошибка, если `bot_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID бота — строка из 24 символов. Возьмите поле `id` из ответа `bots/get`.", "example": "607d97c6a01c6a25972ed95e" } }, "required": [ "bot_id" ] }, "example": { "bot_id": "607d97c6a01c6a25972ed95e" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/Bot" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "607d97c6a01c6a25972ed95e", "name": "Мой бот", "group_id": 123456, "channel": "VK", "active": 0, "archived": 0, "activity_type": "message_new", "create_at": 1704067200 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Бот не найден", "error_code": 7 } } } } } } } } }, "/bots/addUser": { "post": { "tags": [ "Боты" ], "operationId": "botsAddUser", "summary": "Запустить бота для подписчика", "description": "Запускает бота для человека: бот начинает с ним работать со стартового шага или с шага `step_id`. Шаги бота показывает метод `bots/getSteps`.\n\nЕсли этого человека ещё нет среди подписчиков в BotHunter, метод его создаст.\n\nЭто один из первых методов API, и некоторые ошибки у него устроены иначе, чем у новых методов. Если не передан обязательный параметр или шаг не найден, приходит ошибка 6, а не 7. Параметр `channel` передавать обязательно, но бот всё равно работает в своём канале.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Бот не найден»: бота с таким `bot_id` нет или он из чужого сообщества. Та же ошибка, если `bot_id` записан в неверном формате.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».\n- `6` — не передан `bot_id`, `uid` или `channel`; неверный номер пользователя; неверный `step_id` или в боте нет такого шага; добавить пользователя не удалось.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID бота — строка из 24 символов. Возьмите поле `id` из ответа `bots/get`.", "example": "607d97c6a01c6a25972ed95e" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере бота, например id страницы ВКонтакте. Число больше 1.", "example": 102036383 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Передавать обязательно, но бот всё равно работает в своём канале — значение отсюда не используется.", "example": "VK" }, "step_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "С какого шага этого бота начать — поле `id` шага из ответа `bots/getSteps`. Если не передать, бот начнёт со стартового шага.", "example": "607d97c6a01c6a25972ed960" }, "force": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` — запустить бота ещё раз, даже если человек уже проходил его." }, "payload": { "description": "Дополнительные данные, которые бот получит при запуске: объект с любыми полями или строка. Значение поля `text` бот воспримет как текст, с которым его запустили.", "oneOf": [ { "type": "object" }, { "type": "string" } ], "example": { "text": "Текст", "param1": "value1" } } }, "required": [ "bot_id", "uid", "channel" ] }, "example": { "bot_id": "607d97c6a01c6a25972ed95e", "uid": 102036383, "channel": "VK", "force": 1, "payload": { "text": "Текст", "param1": "value1" } } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Бот не найден", "error_code": 7 } } } } } } } } }, "/bots/removeUser": { "post": { "tags": [ "Боты" ], "operationId": "botsRemoveUser", "summary": "Остановить бота для подписчика", "description": "Останавливает бота для человека: бот перестаёт с ним работать.\n\nЕсли подписчика с таким `uid` нет или бот с ним сейчас не работает, ответ всё равно успешный. Ничего не меняется, новый подписчик не создаётся.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Бот не найден»: бота с таким `bot_id` нет или он из чужого сообщества. Та же ошибка, если `bot_id` записан в неверном формате.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».\n- `6` — не передан `bot_id`, `uid` или `channel`; неверный номер пользователя.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID бота — строка из 24 символов. Возьмите поле `id` из ответа `bots/get`.", "example": "607d97c6a01c6a25972ed95e" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере бота, например id страницы ВКонтакте. Число больше 1.", "example": 102036383 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Передавать обязательно, но бот всё равно работает в своём канале — значение отсюда не используется.", "example": "VK" } }, "required": [ "bot_id", "uid", "channel" ] }, "example": { "bot_id": "607d97c6a01c6a25972ed95e", "uid": 102036383, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Бот не найден", "error_code": 7 } } } } } } } } }, "/mailings/get": { "post": { "tags": [ "Рассылки" ], "operationId": "mailingsGet", "summary": "Рассылки сообщества", "description": "Показывает рассылки одного сообщества. Сначала идут новые. Письма цепочек (рассылки с типом `1`) в список не входят.\n\nРассылки бывают только в каналах `VK`, `TG`, `OK` и `MAX`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Рассылки и чат-боты».\n- `7` — неверный статус рассылки в `status`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 6, 7 ], "description": "Показать только рассылки в одном состоянии: `0` — ждёт отправки, `1` — отправляется, `2` — приостановлена, `3` — завершена (кроме тех, что в архиве), `4` — черновик, `6` — в архиве, `7` — ждёт остановки. Если не передать, вернутся все рассылки." }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK", "status": 4 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Mailing" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "65a6e5f4c0e8f20012d3a456", "title": "Акция выходного дня", "type": 4, "status": 3, "status_name": "Завершена", "archived": false, "date_send": 1704067200, "count": 120, "delivered": 118, "no_delivered": 2, "create_at": 1704060000 } ], "total": 1 } } }, "error": { "summary": "Ошибка 8", "value": { "status": "error", "error": "У вас нет доступа для управления этим объектом", "error_code": 8 } } } } } } } } }, "/mailings/getById": { "post": { "tags": [ "Рассылки" ], "operationId": "mailingsGetById", "summary": "Подробно об одной рассылке", "description": "Показывает одну рассылку по её ID. В ответе те же поля, что в `mailings/get`, и ещё: сообщество, текст сообщения и вложения.\n\nВложения приходят в поле `attachments`: у каждого есть `id` и вид `type`, например `photo`. Ссылку на сам файл даёт метод `attachments/getById`.\n\nКому уходит рассылка — списки и другие условия отбора получателей — метод не показывает.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Рассылка не найдена»: рассылки с таким `mailing_id` нет или она из чужого сообщества. Та же ошибка, если `mailing_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mailing_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID рассылки — строка из 24 символов. Возьмите поле `id` из ответа `mailings/get`.", "example": "65a6e5f4c0e8f20012d3a456" } }, "required": [ "mailing_id" ] }, "example": { "mailing_id": "65a6e5f4c0e8f20012d3a456" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/MailingDetails" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "65a6e5f4c0e8f20012d3a456", "title": "Акция выходного дня", "type": 4, "status": 4, "status_name": "Черновик", "archived": false, "date_send": 1704067200, "count": 0, "delivered": 0, "no_delivered": 0, "create_at": 1704060000, "group_id": 123456, "channel": "VK", "message": "Привет! Скидка 20% до воскресенья", "attachments": [ { "id": "65a6e5f4c0e8f20012d3a222", "type": "photo" } ] } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Рассылка не найдена", "error_code": 7 } } } } } } } } }, "/attachments/getById": { "post": { "tags": [ "Рассылки" ], "operationId": "attachmentsGetById", "summary": "Вложение: ссылка на файл", "description": "Показывает одно вложение по его ID: вид, имя файла и ссылку на файл. ID вложений рассылки приходят в поле `attachments` ответа `mailings/getById`.\n\nСсылка `url` — та же, что в интерфейсе BotHunter. У картинки это ссылка на полный размер. У вложения ВКонтакте, которое добавили ссылкой на запись, фото или видео, — ссылка на vk.ru. У вложения без файла, например переменной или контакта, в `url` придёт `null`.\n\nМетод только читает: изменить или удалить вложение через него нельзя.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Вложение не найдено»: вложения с таким `attachment_id` нет или оно из чужого сообщества.\n- `7` — не передан `attachment_id` или он записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID вложения — строка из 24 символов. Возьмите поле `id` из `attachments` в ответе `mailings/getById`.", "example": "65a6e5f4c0e8f20012d3a222" } }, "required": [ "attachment_id" ] }, "example": { "attachment_id": "65a6e5f4c0e8f20012d3a222" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/Attachment" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "65a6e5f4c0e8f20012d3a222", "type": "photo", "title": "banner.jpg", "url": "https://bot-new.targethunter.ru/uploaded/images/65a6e5f4c0e8f20012d3a000/banner.jpg" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Вложение не найдено", "error_code": 7 } } } } } } } } }, "/lists/get": { "post": { "tags": [ "Списки" ], "operationId": "listsGet", "summary": "Списки сообщества", "description": "Показывает обычные списки подписчиков сообщества, сначала новые. `count_users` — сколько подписчиков в списке.\n\nЧёрного списка в ответе нет: методы `lists/*` работают только с обычными списками.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/List" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "65a6e5f4c0e8f20012d3a111", "name": "Клиенты", "count_users": 250 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Группа не найдена", "error_code": 7 } } } } } } } } }, "/lists/create": { "post": { "tags": [ "Списки" ], "operationId": "listsCreate", "summary": "Создать список", "description": "Создаёт в сообществе новый обычный список подписчиков — как кнопка «Создать список» в интерфейсе. Список создаётся пустым: подписчиков в него добавляет `lists/addUser`.\n\nВ ответе придёт созданный список — в том же виде, что в `lists/get`. Его `id` передавайте как `list_id` в остальные методы `lists/*`. Названия списков могут повторяться, как и в интерфейсе.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Лимит:** не больше 20 созданий в минуту и 200 в сутки — вместе с `vars/create` и `globalVars/create`. Считается и попытка с ошибкой в параметрах. Подробнее — в разделе «Ответ и ошибки» в начале справки.\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `7` — «Не указан обязательный параметр name»: `name` не передан или пустой.\n- `7` — «Поле \"Название\" должно принимать значение менее чем 120 символов.»: название длиннее 120 символов.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `5` — «Слишком много созданий: не больше 20 в минуту и 200 в сутки. Повторите позже.»: лимит созданий исчерпан, ничего не создано.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "name": { "type": "string", "maxLength": 120, "description": "Название списка, до 120 символов. Его видно в интерфейсе.", "example": "Клиенты" } }, "required": [ "group_id", "channel", "name" ] }, "example": { "group_id": 123456, "channel": "VK", "name": "Клиенты" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/List" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "65a6e5f4c0e8f20012d3a111", "name": "Клиенты", "count_users": 0 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Не указан обязательный параметр name", "error_code": 7 } } } } } } } } }, "/lists/rename": { "post": { "tags": [ "Списки" ], "operationId": "listsRename", "summary": "Переименовать список", "description": "Меняет название обычного списка — как переименование списка в интерфейсе. Подписчики в списке остаются прежними.\n\nВ ответе придёт список с новым названием — в том же виде, что в `lists/get`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Список не найден»: списка с таким `list_id` нет, он из чужого сообщества или это чёрный список. Та же ошибка, если `list_id` не передан или записан неверно.\n- `7` — «Не указан обязательный параметр name»: `name` не передан или пустой.\n- `7` — «Поле \"Название\" должно принимать значение менее чем 120 символов.»: название длиннее 120 символов.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID списка — строка из 24 символов. Возьмите поле `id` из ответа `lists/get`.", "example": "65a6e5f4c0e8f20012d3a111" }, "name": { "type": "string", "maxLength": 120, "description": "Новое название списка, до 120 символов.", "example": "Постоянные клиенты" } }, "required": [ "list_id", "name" ] }, "example": { "list_id": "65a6e5f4c0e8f20012d3a111", "name": "Постоянные клиенты" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/List" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "65a6e5f4c0e8f20012d3a111", "name": "Постоянные клиенты", "count_users": 250 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Список не найден", "error_code": 7 } } } } } } } } }, "/lists/getUsers": { "post": { "tags": [ "Списки" ], "operationId": "listsGetUsers", "summary": "Подписчики в списке", "description": "Показывает подписчиков одного списка. Сначала идут добавленные последними.\n\nЗа один запрос приходит до 500 подписчиков, по умолчанию 100. Большой список забирайте по страницам: `count` — сколько подписчиков вернуть, `offset` — сколько пропустить от начала.\n\nЕсли запись о подписчике удалена из BotHunter, он в ответ не попадает, но в `total` всё равно учитывается. Поэтому на всех страницах вместе подписчиков может оказаться меньше, чем `total`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Список не найден»: списка с таким `list_id` нет, он из чужого сообщества или это чёрный список. Та же ошибка, если `list_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID списка — строка из 24 символов. Возьмите поле `id` из ответа `lists/get`.", "example": "65a6e5f4c0e8f20012d3a111" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько подписчиков вернуть за один запрос. По умолчанию 100, не больше 500: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько подписчиков пропустить от начала списка. Вторая страница по 100 подписчиков — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "list_id" ] }, "example": { "list_id": "65a6e5f4c0e8f20012d3a111", "count": 100, "offset": 0 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListUser" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "uid": 102036383, "name": "Иван Петров", "added_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Список не найден", "error_code": 7 } } } } } } } } }, "/lists/addUser": { "post": { "tags": [ "Списки" ], "operationId": "listsAddUser", "summary": "Добавить подписчика в список", "description": "Добавляет подписчика в обычный список.\n\nЧеловек должен уже быть подписчиком сообщества, которому принадлежит список: новых подписчиков метод не создаёт. Если подписчик уже в списке, повторный вызов ничего не меняет.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Список не найден»: списка с таким `list_id` нет, он из чужого сообщества или это чёрный список. Та же ошибка, если `list_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».\n- `7` — «Подписчик не найден»: такого человека нет среди подписчиков сообщества или `uid` неверный.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID списка — строка из 24 символов. Возьмите поле `id` из ответа `lists/get`.", "example": "65a6e5f4c0e8f20012d3a111" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере, например id страницы ВКонтакте или id пользователя Telegram.", "example": 102036383 } }, "required": [ "list_id", "uid" ] }, "example": { "list_id": "65a6e5f4c0e8f20012d3a111", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Подписчик не найден", "error_code": 7 } } } } } } } } }, "/lists/removeUser": { "post": { "tags": [ "Списки" ], "operationId": "listsRemoveUser", "summary": "Убрать подписчика из списка", "description": "Убирает подписчика из списка.\n\nПодписан ли человек на сообщество, метод не проверяет: из списка можно убрать и того, кто уже отписался. Если человека в списке не было, ничего не меняется.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Список не найден»: списка с таким `list_id` нет, он из чужого сообщества или это чёрный список. Та же ошибка, если `list_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».\n- `7` — «Подписчик не найден»: такого человека вообще нет в этом канале или `uid` неверный.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID списка — строка из 24 символов. Возьмите поле `id` из ответа `lists/get`.", "example": "65a6e5f4c0e8f20012d3a111" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере, например id страницы ВКонтакте или id пользователя Telegram.", "example": 102036383 } }, "required": [ "list_id", "uid" ] }, "example": { "list_id": "65a6e5f4c0e8f20012d3a111", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Список не найден", "error_code": 7 } } } } } } } } }, "/contacts/getById": { "post": { "tags": [ "Контакты" ], "operationId": "contactsGetById", "summary": "Карточка подписчика", "description": "Показывает карточку одного подписчика сообщества.\n\nИмя приходит с учётом правки: если его поменяли в карточке контакта, придёт новое. Телефон и почта — из карточки контакта в этом сообществе. Если какого-то поля нет, в нём `null`; только `name` в таком случае — пустая строка.\n\nМетод только читает данные: новых подписчиков он не создаёт.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `7` — «Подписчик не найден»: такого человека нет среди подписчиков сообщества или `uid` неверный.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере, например id страницы ВКонтакте или id пользователя Telegram.", "example": 102036383 } }, "required": [ "group_id", "channel", "uid" ] }, "example": { "group_id": 123456, "channel": "VK", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/Contact" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "uid": 102036383, "name": "Иван Петров", "first_name": "Иван", "last_name": "Петров", "username": "ivan_petrov", "phone": "+79001234567", "email": null, "create_at": 1704067200 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Подписчик не найден", "error_code": 7 } } } } } } } } }, "/contacts/getVars": { "post": { "tags": [ "Контакты" ], "operationId": "contactsGetVars", "summary": "Переменные подписчика", "description": "Показывает пользовательские переменные и их значения у одного подписчика. Пользовательские переменные — это поля, которые создают в сообществе, чтобы хранить данные о людях: например, город или число бонусов.\n\nПеременные и их порядок — такие же, как в `vars/list`: сначала новые. Если у подписчика значения нет, в `value` придёт `null`.\n\n`id` переменной из ответа можно передать как `var_id` в `vars/set` и `vars/clear`, чтобы записать или стереть значение.\n\nВременные переменные ботов — ответы, которые сохранили блоки бота, — в список не входят.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `7` — «Подписчик не найден»: такого человека нет среди подписчиков сообщества или `uid` неверный.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере, например id страницы ВКонтакте или id пользователя Telegram.", "example": 102036383 }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel", "uid" ] }, "example": { "group_id": 123456, "channel": "VK", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContactVariable" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "61af67fb5bc8635f3f53b18b", "title": "Бонусы", "name": "bonus", "value": "150" }, { "id": "61af67fb5bc8635f3f53b18c", "title": "Город", "name": "city", "value": null } ], "total": 2 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Подписчик не найден", "error_code": 7 } } } } } } } } }, "/contacts/getLists": { "post": { "tags": [ "Контакты" ], "operationId": "contactsGetLists", "summary": "Списки подписчика", "description": "Показывает списки сообщества, в которых состоит подписчик. Это те же списки, что во вкладке «Списки» карточки подписчика в CRM. Чёрный список в ответ не входит.\n\nСначала идут списки, куда подписчика добавили последними. Списки подписчиков лендингов в ответ не входят.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `7` — «Подписчик не найден»: такого человека нет среди подписчиков сообщества или `uid` неверный.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере, например id страницы ВКонтакте или id пользователя Telegram.", "example": 102036383 }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel", "uid" ] }, "example": { "group_id": 123456, "channel": "VK", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContactList" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "65a6e5f4c0e8f20012d3a111", "name": "Клиенты", "added_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Подписчик не найден", "error_code": 7 } } } } } } } } }, "/contacts/getBots": { "post": { "tags": [ "Контакты" ], "operationId": "contactsGetBots", "summary": "Боты подписчика", "description": "Показывает ботов сообщества, которые сейчас работают с подписчиком, — то же, что вкладка «Боты» в карточке подписчика в CRM. Ботов, которых подписчик уже прошёл до конца, в ответе нет.\n\nСначала идёт бот, в который подписчик вошёл последним. Остановить бота для подписчика можно методом `bots/removeUser`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `7` — «Подписчик не найден»: такого человека нет среди подписчиков сообщества или `uid` неверный.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере, например id страницы ВКонтакте или id пользователя Telegram.", "example": 102036383 }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel", "uid" ] }, "example": { "group_id": 123456, "channel": "VK", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContactBot" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "607d97c6a01c6a25972ed95e", "name": "Запись на консультацию", "steps": [ { "id": "607d97c6a01c6a25972ed960", "title": "Выбор времени", "step_entered_at": 1704067300, "bot_entered_at": 1704067200 } ] } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Подписчик не найден", "error_code": 7 } } } } } } } } }, "/vars/list": { "post": { "tags": [ "Пользовательские переменные" ], "operationId": "varsList", "summary": "Список пользовательских переменных", "description": "Показывает, какие пользовательские переменные есть в сообществе. Пользовательская переменная хранит у каждого подписчика своё значение: например, город или число бонусов. Сначала идут новые.\n\nМетод возвращает только сами переменные, без значений. Значение у одного подписчика читает `vars/get`, а все значения подписчика сразу — `contacts/getVars`.\n\n`id` переменной передавайте как `var_id` в `vars/get`, `vars/set` и `vars/clear`. `name` — имя для подстановки в тексты: переменная с именем `city` подставится в сообщение как `{%city%}`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Variable" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "61af67fb5bc8635f3f53b18b", "title": "Бонусы", "name": "bonus", "create_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Группа не найдена", "error_code": 7 } } } } } } } } }, "/vars/create": { "post": { "tags": [ "Пользовательские переменные" ], "operationId": "varsCreate", "summary": "Создать пользовательскую переменную", "description": "Создаёт в сообществе новую пользовательскую переменную — как кнопка «Создать переменную» в интерфейсе. Значений у подписчиков сразу нет: записать значение подписчику можно через `vars/set`.\n\nВ ответе придёт созданная переменная — в том же виде, что в `vars/list`. Её `id` передавайте как `var_id` в `vars/get`, `vars/set` и `vars/clear`.\n\nКороткое имя `name` проверяется так же, как в интерфейсе: в нём нельзя использовать символы `.` `{` `}` `[` `]` `%` `|` `'` `\"` `` ` `` `:` `;` и сочетание `_NAME`. Имя должно быть свободно: двух переменных с одним коротким именем в сообществе быть не может. Название и короткое имя — не длиннее 120 символов.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Лимит:** не больше 20 созданий в минуту и 200 в сутки — вместе с `lists/create` и `globalVars/create`. Считается и попытка с ошибкой в параметрах. Подробнее — в разделе «Ответ и ошибки» в начале справки.\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `7` — «Не указан обязательный параметр title» или «… name»: параметр не передан или пустой.\n- `7` — «Параметр title: максимальная длина 120 символов» или то же про `name`: значение длиннее 120 символов.\n- `7` — «В коротком имени не должно быть символа: «:»»: в `name` запрещённый символ, в кавычках — какой именно.\n- `7` — «Переменная \"bonus\" уже существует»: такое короткое имя в сообществе уже занято.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `5` — «Слишком много созданий: не больше 20 в минуту и 200 в сутки. Повторите позже.»: лимит созданий исчерпан, ничего не создано.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "title": { "type": "string", "maxLength": 120, "description": "Название переменной, до 120 символов. Его видно в интерфейсе.", "example": "Бонусы" }, "name": { "type": "string", "maxLength": 120, "description": "Короткое имя для подстановки в тексты: переменная с именем `bonus` подставится в сообщение как `{%bonus%}`. До 120 символов, без символы `.` `{` `}` `[` `]` `%` `|` `'` `\"` `` ` `` `:` `;` и сочетание `_NAME`. Должно быть свободно в сообществе.", "example": "bonus" } }, "required": [ "group_id", "channel", "title", "name" ] }, "example": { "group_id": 123456, "channel": "VK", "title": "Бонусы", "name": "bonus" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/Variable" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "61af67fb5bc8635f3f53b18b", "title": "Бонусы", "name": "bonus", "create_at": 1704067200 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная \"bonus\" уже существует", "error_code": 7 } } } } } } } } }, "/vars/get": { "post": { "tags": [ "Пользовательские переменные" ], "operationId": "varsGet", "summary": "Значение переменной у подписчика", "description": "Показывает значение одной пользовательской переменной у одного подписчика.\n\nЕсли значения нет или подписчика с таким `uid` нет, придёт `value: null`. Новый подписчик при этом не создаётся.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Переменная не найдена»: переменной с таким `var_id` нет или она из чужого сообщества. Та же ошибка, если `var_id` не передан или записан неверно.\n- `7` — не передан `uid` или это не число.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "var_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID пользовательской переменной — строка из 24 символов. Возьмите поле `id` из ответа `vars/list` или `contacts/getVars`.", "example": "61af67fb5bc8635f3f53b18b" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере того сообщества, где создана переменная. Число.", "example": 102036383 } }, "required": [ "var_id", "uid" ] }, "example": { "var_id": "61af67fb5bc8635f3f53b18b", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/VariableValue" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "title": "Бонусы", "name": "bonus", "value": "150" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная не найдена", "error_code": 7 } } } } } } } } }, "/vars/set": { "post": { "tags": [ "Пользовательские переменные" ], "operationId": "varsSet", "summary": "Записать значение переменной", "description": "Записывает подписчику значение пользовательской переменной. Если подписчика с таким `uid` ещё нет, метод его создаст.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Переменная не найдена»: переменной с таким `var_id` нет или она из чужого сообщества. Та же ошибка, если `var_id` не передан или записан неверно.\n- `7` — не передан `uid` или это не число; в `value` передан массив или объект.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».\n- `6` — не передан `value`. Это один из первых методов API, и у этой ошибки исторически код 6, а не 7.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "var_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID пользовательской переменной — строка из 24 символов. Возьмите поле `id` из ответа `vars/list` или `contacts/getVars`.", "example": "61af67fb5bc8635f3f53b18b" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере того сообщества, где создана переменная. Число.", "example": 102036383 }, "value": { "description": "Новое значение: строка или число. Сохраняется как строка. Если передать массив или объект, придёт ошибка 7.", "oneOf": [ { "type": "string" }, { "type": "number" } ], "example": "150" } }, "required": [ "var_id", "uid", "value" ] }, "example": { "var_id": "61af67fb5bc8635f3f53b18b", "uid": 102036383, "value": "150" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная не найдена", "error_code": 7 } } } } } } } } }, "/vars/clear": { "post": { "tags": [ "Пользовательские переменные" ], "operationId": "varsClear", "summary": "Очистить переменную у подписчика", "description": "Стирает значение пользовательской переменной у подписчика. Если подписчика с таким `uid` нет, ответ всё равно успешный и ничего не меняется.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Переменная не найдена»: переменной с таким `var_id` нет или она из чужого сообщества. Та же ошибка, если `var_id` не передан или записан неверно.\n- `7` — не передан `uid` или это не число.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "var_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID пользовательской переменной — строка из 24 символов. Возьмите поле `id` из ответа `vars/list` или `contacts/getVars`.", "example": "61af67fb5bc8635f3f53b18b" }, "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере того сообщества, где создана переменная. Число.", "example": 102036383 } }, "required": [ "var_id", "uid" ] }, "example": { "var_id": "61af67fb5bc8635f3f53b18b", "uid": 102036383 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная не найдена", "error_code": 7 } } } } } } } } }, "/globalVars/list": { "post": { "tags": [ "Переменные сообщества" ], "operationId": "globalVarsList", "summary": "Список переменных сообщества", "description": "Показывает переменные сообщества вместе со значениями. Переменная сообщества хранит одно значение на всё сообщество, одинаковое для всех подписчиков: например, промокод недели. Сначала идут новые.\n\nВ ответ входят только переменные, созданные в этом сообществе. Если другое сообщество открыло этому доступ к своей переменной сообщества, её читают и меняют через сообщество, где она создана.\n\n`id` переменной передавайте как `var_id` в `globalVars/get`, `globalVars/set` и `globalVars/clear`. `value` — текущее значение.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalVariable" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "61af67fb5bc8635f3f53b18d", "title": "Промокод недели", "name": "promo", "value": "AUTUMN20", "create_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Группа не найдена", "error_code": 7 } } } } } } } } }, "/globalVars/create": { "post": { "tags": [ "Переменные сообщества" ], "operationId": "globalVarsCreate", "summary": "Создать переменную сообщества", "description": "Создаёт в сообществе новую переменную сообщества — как кнопка «Создать переменную» на вкладке переменных сообщества в интерфейсе. Начальное значение можно передать сразу в `value` или записать позже через `globalVars/set`.\n\nВ ответе придёт созданная переменная — в том же виде, что в `globalVars/list`. Её `id` передавайте как `var_id` в `globalVars/get`, `globalVars/set` и `globalVars/clear`.\n\nКороткое имя `name` проверяется так же, как в интерфейсе: в нём нельзя использовать символы `.` `{` `}` `[` `]` `%` `|` `'` `\"` `` ` `` `:` `;` и сочетание `_NAME`. Имя должно быть свободно: двух переменных с одним коротким именем в сообществе быть не может. Название и короткое имя — не длиннее 120 символов.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Лимит:** не больше 20 созданий в минуту и 200 в сутки — вместе с `lists/create` и `vars/create`. Считается и попытка с ошибкой в параметрах. Подробнее — в разделе «Ответ и ошибки» в начале справки.\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `7` — «Не указан обязательный параметр title» или «… name»: параметр не передан или пустой.\n- `7` — «Параметр title: максимальная длина 120 символов» или то же про `name`: значение длиннее 120 символов.\n- `7` — «Параметр value должен быть строкой»: в `value` передан массив или объект.\n- `7` — «Превышен допустимый объем символов значения переменной»: значение длиннее 32 000 символов.\n- `7` — «В коротком имени не должно быть символа: «:»»: в `name` запрещённый символ, в кавычках — какой именно.\n- `7` — «Переменная \"promo\" уже существует»: такое короткое имя в сообществе уже занято.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Пользователи».\n- `5` — «Слишком много созданий: не больше 20 в минуту и 200 в сутки. Повторите позже.»: лимит созданий исчерпан, ничего не создано.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "title": { "type": "string", "maxLength": 120, "description": "Название переменной, до 120 символов. Его видно в интерфейсе.", "example": "Промокод недели" }, "name": { "type": "string", "maxLength": 120, "description": "Короткое имя для подстановки в тексты. До 120 символов, без символы `.` `{` `}` `[` `]` `%` `|` `'` `\"` `` ` `` `:` `;` и сочетание `_NAME`. Должно быть свободно в сообществе.", "example": "promo" }, "value": { "description": "Начальное значение: строка или число, до 32 000 символов. Сохраняется как строка. Если не передать, переменная создастся с пустым значением.", "oneOf": [ { "type": "string", "maxLength": 32000 }, { "type": "number" } ], "example": "AUTUMN20" } }, "required": [ "group_id", "channel", "title", "name" ] }, "example": { "group_id": 123456, "channel": "VK", "title": "Промокод недели", "name": "promo", "value": "AUTUMN20" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/GlobalVariable" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "61af67fb5bc8635f3f53b18d", "title": "Промокод недели", "name": "promo", "value": "AUTUMN20", "create_at": 1704067200 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная \"promo\" уже существует", "error_code": 7 } } } } } } } } }, "/globalVars/get": { "post": { "tags": [ "Переменные сообщества" ], "operationId": "globalVarsGet", "summary": "Значение переменной сообщества", "description": "Показывает значение переменной сообщества. Такая переменная одна на всё сообщество: её значение не зависит от подписчика. Например, промокод недели.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Переменная не найдена»: переменной с таким `var_id` нет или она из чужого сообщества. Та же ошибка, если `var_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "var_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID переменной сообщества — строка из 24 символов. Возьмите поле `id` из ответа `globalVars/list`.", "example": "61af67fb5bc8635f3f53b18d" } }, "required": [ "var_id" ] }, "example": { "var_id": "61af67fb5bc8635f3f53b18d" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/VariableValue" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "title": "Промокод недели", "name": "promo", "value": "AUTUMN20" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная не найдена", "error_code": 7 } } } } } } } } }, "/globalVars/set": { "post": { "tags": [ "Переменные сообщества" ], "operationId": "globalVarsSet", "summary": "Записать переменную сообщества", "description": "Записывает новое значение переменной сообщества.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Переменная не найдена»: переменной с таким `var_id` нет или она из чужого сообщества. Та же ошибка, если `var_id` не передан или записан неверно.\n- `7` — в `value` передан массив или объект.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».\n- `6` — не передан `value`. Это один из первых методов API, и у этой ошибки исторически код 6, а не 7.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "var_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID переменной сообщества — строка из 24 символов. Возьмите поле `id` из ответа `globalVars/list`.", "example": "61af67fb5bc8635f3f53b18d" }, "value": { "description": "Новое значение: строка или число. Сохраняется как строка. Если передать массив или объект, придёт ошибка 7.", "oneOf": [ { "type": "string" }, { "type": "number" } ], "example": "150" } }, "required": [ "var_id", "value" ] }, "example": { "var_id": "61af67fb5bc8635f3f53b18d", "value": "AUTUMN20" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная не найдена", "error_code": 7 } } } } } } } } }, "/globalVars/clear": { "post": { "tags": [ "Переменные сообщества" ], "operationId": "globalVarsClear", "summary": "Очистить переменную сообщества", "description": "Стирает значение переменной сообщества.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Пользователи».\n\n**Ошибки метода:**\n- `7` — «Переменная не найдена»: переменной с таким `var_id` нет или она из чужого сообщества. Та же ошибка, если `var_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Пользователи».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "var_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID переменной сообщества — строка из 24 символов. Возьмите поле `id` из ответа `globalVars/list`.", "example": "61af67fb5bc8635f3f53b18d" } }, "required": [ "var_id" ] }, "example": { "var_id": "61af67fb5bc8635f3f53b18d" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "description": "У действия нет результата, поэтому поля `response` в ответе нет — так в обеих версиях API." }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok" } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Переменная не найдена", "error_code": 7 } } } } } } } } }, "/landings/get": { "post": { "tags": [ "Лендинги" ], "operationId": "landingsGet", "summary": "Лендинги сообщества", "description": "Показывает лендинги сообщества. Сначала идут мини-лендинги (`kind: \"mini\"`), за ними — мультиканальные лендинги, на которых есть кнопка этого сообщества (`kind: \"multichannel\"`). В каждой из двух частей новые идут первыми.\n\nМультиканальных лендингов учитывается не больше 1000 — так же, как в интерфейсе.\n\nСтатистику одного лендинга (`stats/getLandingStats`) можно получить только для мини-лендинга.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с любой ролью.\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Landing" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "65a6e5f4c0e8f20012d3a456", "title": "Подписка на новости", "kind": "mini", "url": "https://bothunter.ai/p/65a6e5f4c0e8f20012d3a456", "create_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Группа не найдена", "error_code": 7 } } } } } } } } }, "/funnels/get": { "post": { "tags": [ "Воронки" ], "operationId": "funnelsGet", "summary": "Воронки сообщества", "description": "Показывает воронки сообщества. Сначала идут новые. Статистику по шагам одной воронки показывает `funnels/getById`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с любой ролью.\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "count": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500, "description": "Сколько записей вернуть за один запрос. По умолчанию 100. Больше 500 не вернётся: большее число сервер заменит на 500." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Funnel" } }, "total": { "type": "integer", "description": "Сколько всего записей подходит под условия запроса — на всех страницах вместе, а не только в этом ответе" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "items": [ { "id": "65a6e5f4c0e8f20012d3a456", "title": "Запись на консультацию", "create_at": 1704067200 } ], "total": 1 } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Группа не найдена", "error_code": 7 } } } } } } } } }, "/funnels/getById": { "post": { "tags": [ "Воронки" ], "operationId": "funnelsGetById", "summary": "Воронка со статистикой", "description": "Показывает одну воронку со статистикой по каждому шагу. Цифры считаются так же, как при открытии воронки в интерфейсе.\n\nЧисло подписчиков на шаге считается на текущий момент. Если воронка заморожена — на дату заморозки (поле `freeze_at`). Выбрать другой период нельзя.\n\nРасчёт долгий, поэтому готовый ответ хранится 60 секунд. Если повторить запрос в течение минуты, придёт тот же результат. Когда статистику посчитали, показывает поле `counted_at`.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с любой ролью.\n\n**Ошибки метода:**\n- `7` — «Воронка не найдена»: воронки с таким `funnel_id` нет или она из чужого сообщества. Та же ошибка, если `funnel_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник сообщества, которому принадлежит воронка.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "funnel_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID воронки — строка из 24 символов. Возьмите поле `id` из ответа `funnels/get`.", "example": "65a6e5f4c0e8f20012d3a456" } }, "required": [ "funnel_id" ] }, "example": { "funnel_id": "65a6e5f4c0e8f20012d3a456" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "$ref": "#/components/schemas/FunnelDetails" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "id": "65a6e5f4c0e8f20012d3a456", "title": "Запись на консультацию", "budget": 5000, "budget_type": "custom", "source_only": false, "freeze_at": null, "create_at": 1704067200, "counted_at": 1735689600, "steps": [ { "id": "65a6e5f4c0e8f20012d3a457", "type": "start", "title": "Подписались", "count": 200, "cost": 25, "values": 0, "avg_value": 0, "profit": -25, "reach_percent": null, "connects": [ "65a6e5f4c0e8f20012d3a458" ], "connected_percents": { "65a6e5f4c0e8f20012d3a458": "40" } } ] } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Воронка не найдена", "error_code": 7 } } } } } } } } }, "/stats/getMailingsStats": { "post": { "tags": [ "Статистика" ], "operationId": "statsGetMailingsStats", "summary": "Статистика рассылок сообщества", "description": "Показывает статистику всех рассылок сообщества по дням: доставки, прочтения и переходы по ссылкам. Период — не больше 92 дней.\n\nПрочтения и переходы отмечаются только у сообщений ВКонтакте. Поэтому фильтры `reading_mailing` и `followed_link` работают только для ВКонтакте: в других каналах любое значение, кроме `0`, даёт ошибку 7.\n\nПериод можно не указывать. Без `date_to` он заканчивается текущим моментом, без `date_from` — начинается за 7 дней до `date_to`. В ответе `date_from` и `date_to` показывают, за какой период посчитана статистика.\n\nДаты в ответах методов `stats/*` приходят строками, например `01.09.2026 00:00`, а не unix-временем, как в других разделах.\n\n**В v1:** параметр `uid` не учитывается; если `date_from` позже `date_to`, ошибки нет.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Рассылки и чат-боты».\n- `7` — неверный формат даты или `date_from` позже `date_to` (вторая проверка — только в v2).\n- `7` — «Период не больше 92 дней».\n- `7` — неверное значение `reading_mailing`, `followed_link` или `delivery_status`; фильтр прочтений или переходов для сообщества не из ВКонтакте.\n- `6` — «Пользователь не найден»: подписчика с номером из `user_id` или `uid` нет.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "date_from": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Начало периода в формате `dd.mm.yyyy hh:ii` по московскому времени, например `01.09.2026 00:00`. Если не указать — за 7 дней до `date_to`.", "example": "01.01.2026 00:00" }, "date_to": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Конец периода в формате `dd.mm.yyyy hh:ii` по московскому времени. Если не указать — текущий момент.", "example": "01.01.2026 00:00" }, "reading_mailing": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "Прочтение: `0` — все сообщения, `1` — только прочитанные, `2` — только непрочитанные. Работает только для ВКонтакте." }, "followed_link": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "Переходы по ссылке: `0` — все сообщения, `1` — только те, где перешли по ссылке, `2` — где не перешли. Работает только для ВКонтакте." }, "delivery_status": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "Доставка: `0` — все сообщения, `1` — только доставленные, `2` — только недоставленные." }, "user_id": { "type": "integer", "description": "Посчитать только сообщения одному подписчику. Передайте его номер в соцсети или мессенджере. Если такого подписчика нет, придёт ошибка 6 «Пользователь не найден».", "example": 102036383 }, "uid": { "type": "integer", "description": "То же, что `user_id`. В остальных методах номер человека называется `uid`, поэтому в v2 здесь принимается и это имя. Если переданы оба, действует `user_id`. Работает только в v2.", "example": 102036383 } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK", "date_from": "25.12.2025 00:00", "date_to": "01.01.2026 00:00" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "chart": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MailingChartItem" } }, "total": { "$ref": "#/components/schemas/MailingChartTotal" } } }, "date_from": { "type": "string", "description": "Начало периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" }, "date_to": { "type": "string", "description": "Конец периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "chart": { "items": [ { "date": "1.1.2026", "delivered": 10, "not_delivered": 1, "reads": 4, "clicks": 2 } ], "total": { "delivered": 10, "not_delivered": 1, "reads": 4, "clicks": 2 } }, "date_from": "25.12.2025 00:00", "date_to": "01.01.2026 00:00" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Период не больше 92 дней", "error_code": 7 } } } } } } } } }, "/stats/getMailingStats": { "post": { "tags": [ "Статистика" ], "operationId": "statsGetMailingStats", "summary": "Статистика одной рассылки", "description": "Показывает статистику одной рассылки по дням: доставки, прочтения и переходы по ссылкам. В поле `chart` — массив дней, в `total` — суммы за весь период.\n\nЕсли не передать ни одной даты, период начинается с начала дня, когда рассылку отправили, и заканчивается текущим моментом. Ограничения в 92 дня у этого метода нет.\n\nПериод можно не указывать. Без `date_to` он заканчивается текущим моментом, без `date_from` — начинается за 7 дней до `date_to`. В ответе `date_from` и `date_to` показывают, за какой период посчитана статистика.\n\nДаты в ответах методов `stats/*` приходят строками, например `01.09.2026 00:00`, а не unix-временем, как в других разделах.\n\n**В v1:** поля `total` в ответе нет; параметр `uid` не учитывается; если `date_from` позже `date_to`, ошибки нет.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Рассылки и чат-боты».\n\n**Ошибки метода:**\n- `7` — «Рассылка не найдена»: рассылки с таким `mailing_id` нет или она из чужого сообщества. Та же ошибка, если `mailing_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Рассылки и чат-боты».\n- `7` — неверный формат даты или `date_from` позже `date_to` (вторая проверка — только в v2).\n- `7` — неверное значение `reading_mailing`, `followed_link` или `delivery_status`; фильтр прочтений или переходов для сообщества не из ВКонтакте.\n- `6` — «Пользователь не найден»: подписчика с номером из `user_id` или `uid` нет.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mailing_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID рассылки — строка из 24 символов. Возьмите поле `id` из ответа `mailings/get`.", "example": "65a6e5f4c0e8f20012d3a456" }, "date_from": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Начало периода в формате `dd.mm.yyyy hh:ii` по московскому времени, например `01.09.2026 00:00`. Если не указать — за 7 дней до `date_to`.", "example": "01.01.2026 00:00" }, "date_to": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Конец периода в формате `dd.mm.yyyy hh:ii` по московскому времени. Если не указать — текущий момент.", "example": "01.01.2026 00:00" }, "reading_mailing": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "Прочтение: `0` — все сообщения, `1` — только прочитанные, `2` — только непрочитанные. Работает только для ВКонтакте." }, "followed_link": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "Переходы по ссылке: `0` — все сообщения, `1` — только те, где перешли по ссылке, `2` — где не перешли. Работает только для ВКонтакте." }, "delivery_status": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "Доставка: `0` — все сообщения, `1` — только доставленные, `2` — только недоставленные." }, "user_id": { "type": "integer", "description": "Посчитать только сообщения одному подписчику. Передайте его номер в соцсети или мессенджере. Если такого подписчика нет, придёт ошибка 6 «Пользователь не найден».", "example": 102036383 }, "uid": { "type": "integer", "description": "То же, что `user_id`. В остальных методах номер человека называется `uid`, поэтому в v2 здесь принимается и это имя. Если переданы оба, действует `user_id`. Работает только в v2.", "example": 102036383 } }, "required": [ "mailing_id" ] }, "example": { "mailing_id": "65a6e5f4c0e8f20012d3a456", "date_from": "01.01.2026 00:00", "date_to": "07.01.2026 23:59" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "mailing_id": { "type": "string", "description": "ID рассылки" }, "mailing_name": { "type": "string", "description": "Название рассылки" }, "chart": { "type": "array", "items": { "$ref": "#/components/schemas/MailingChartItem" } }, "total": { "$ref": "#/components/schemas/MailingChartTotal" }, "date_from": { "type": "string", "description": "Начало периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" }, "date_to": { "type": "string", "description": "Конец периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "mailing_id": "65a6e5f4c0e8f20012d3a456", "mailing_name": "Акция выходного дня", "chart": [ { "date": "1.1.2026", "delivered": 10, "not_delivered": 1, "reads": 4, "clicks": 2 } ], "total": { "delivered": 10, "not_delivered": 1, "reads": 4, "clicks": 2 }, "date_from": "01.01.2026 00:00", "date_to": "07.01.2026 23:59" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Рассылка не найдена", "error_code": 7 } } } } } } } } }, "/stats/getLandingsStats": { "post": { "tags": [ "Статистика" ], "operationId": "statsGetLandingsStats", "summary": "Статистика лендингов сообщества", "description": "Показывает по дням, сколько подписок и отписок было на всех лендингах сообщества. Период — не больше 366 дней.\n\nПериод можно не указывать. Без `date_to` он заканчивается текущим моментом, без `date_from` — начинается за 7 дней до `date_to`. В ответе `date_from` и `date_to` показывают, за какой период посчитана статистика.\n\nДаты в ответах методов `stats/*` приходят строками, например `01.09.2026 00:00`, а не unix-временем, как в других разделах.\n\n**В v1:** если `date_from` позже `date_to`, ошибки нет.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Статистика».\n\n**Ошибки метода:**\n- `7` — не передан `group_id` или `channel`, значение неверное или такого сообщества нет.\n- `8` — «У вас нет доступа для управления этим объектом»: вы не владелец и не сотрудник этого сообщества или у вас нет роли «Статистика».\n- `7` — неверный формат даты или `date_from` позже `date_to` (вторая проверка — только в v2).\n- `7` — «Период не больше 366 дней».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере. Возьмите поле `group_id` из ответа `groups/get`.", "example": 123456 }, "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито. Можно писать и маленькими буквами.", "example": "VK" }, "date_from": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Начало периода в формате `dd.mm.yyyy hh:ii` по московскому времени, например `01.09.2026 00:00`. Если не указать — за 7 дней до `date_to`.", "example": "01.01.2026 00:00" }, "date_to": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Конец периода в формате `dd.mm.yyyy hh:ii` по московскому времени. Если не указать — текущий момент.", "example": "01.01.2026 00:00" } }, "required": [ "group_id", "channel" ] }, "example": { "group_id": 123456, "channel": "VK", "date_from": "25.12.2025 00:00", "date_to": "01.01.2026 00:00" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "subscribed": { "type": "integer", "description": "Подписались за период" }, "unsubscribed": { "type": "integer", "description": "Отписались за период" }, "chart": { "type": "array", "items": { "$ref": "#/components/schemas/LandingChartItem" } }, "date_from": { "type": "string", "description": "Начало периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" }, "date_to": { "type": "string", "description": "Конец периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "subscribed": 2, "unsubscribed": 1, "chart": [ { "date": "2026-01-01", "subscribed": 1, "unsubscribed": 0 }, { "date": "2026-01-02", "subscribed": 1, "unsubscribed": 1 } ], "date_from": "25.12.2025 00:00", "date_to": "01.01.2026 00:00" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Период не больше 366 дней", "error_code": 7 } } } } } } } } }, "/stats/getLandingStats": { "post": { "tags": [ "Статистика" ], "operationId": "statsGetLandingStats", "summary": "Статистика одного мини-лендинга", "description": "Показывает по дням подписки и отписки на одном мини-лендинге. Мини-лендинги в ответе `landings/get` отмечены `kind: \"mini\"`. Период — не больше 366 дней.\n\nПериод можно не указывать. Без `date_to` он заканчивается текущим моментом, без `date_from` — начинается за 7 дней до `date_to`. В ответе `date_from` и `date_to` показывают, за какой период посчитана статистика.\n\nДаты в ответах методов `stats/*` приходят строками, например `01.09.2026 00:00`, а не unix-временем, как в других разделах.\n\n**В v1:** если `date_from` позже `date_to`, ошибки нет.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Статистика».\n\n**Ошибки метода:**\n- `7` — «Лендинг не найден»: мини-лендинга с таким `landing_id` нет или он из чужого сообщества. Та же ошибка, если `landing_id` не передан или записан неверно.\n- `8` — «У вас нет доступа для управления этим объектом»: вы сотрудник сообщества, но у вас нет роли «Статистика».\n- `7` — неверный формат даты или `date_from` позже `date_to` (вторая проверка — только в v2).\n- `7` — «Период не больше 366 дней».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "landing_id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "ID мини-лендинга — строка из 24 символов. Возьмите поле `id` из ответа `landings/get` у лендинга с `kind: \"mini\"`.", "example": "65a6e5f4c0e8f20012d3a111" }, "date_from": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Начало периода в формате `dd.mm.yyyy hh:ii` по московскому времени, например `01.09.2026 00:00`. Если не указать — за 7 дней до `date_to`.", "example": "01.01.2026 00:00" }, "date_to": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Конец периода в формате `dd.mm.yyyy hh:ii` по московскому времени. Если не указать — текущий момент.", "example": "01.01.2026 00:00" } }, "required": [ "landing_id" ] }, "example": { "landing_id": "65a6e5f4c0e8f20012d3a111", "date_from": "25.12.2025 00:00", "date_to": "01.01.2026 00:00" } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "landing_id": { "type": "string", "description": "ID лендинга" }, "landing_name": { "type": "string", "description": "Название лендинга" }, "subscribed": { "type": "integer", "description": "Подписались за период" }, "unsubscribed": { "type": "integer", "description": "Отписались за период" }, "chart": { "type": "array", "items": { "$ref": "#/components/schemas/LandingChartItem" } }, "date_from": { "type": "string", "description": "Начало периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" }, "date_to": { "type": "string", "description": "Конец периода, за который посчитана статистика, в формате `dd.mm.yyyy hh:ii`" } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "landing_id": "65a6e5f4c0e8f20012d3a111", "landing_name": "Подписка на новости", "subscribed": 1, "unsubscribed": 0, "chart": [ { "date": "2026-01-01", "subscribed": 1, "unsubscribed": 0 } ], "date_from": "25.12.2025 00:00", "date_to": "01.01.2026 00:00" } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Лендинг не найден", "error_code": 7 } } } } } } } } }, "/stats/getAdsSubscribes": { "post": { "tags": [ "Статистика" ], "operationId": "statsGetAdsSubscribes", "summary": "Подписки по рекламным меткам", "description": "Показывает подписки и отписки, пришедшие с рекламы, по UTM-меткам. UTM-метки — это параметры в ссылке (`utm_source`, `utm_campaign` и другие), по которым видно, из какой рекламы пришёл человек.\n\nМетод ищет во всех сообществах ВКонтакте, где вам открыта статистика. События идут от ранних к поздним.\n\nНужно передать хотя бы одну метку. Период обязателен и не длиннее 90 дней.\n\nОтвет устроен не так, как у других списков: `count` в ответе — сколько событий пришло в этом ответе, а на одной странице может быть до 1000 событий. Поля `user` и `subscription` приходят, только если подписчик и лендинг ещё существуют. Своего ID у события нет.\n\n**В v1:** если `date_from` позже `date_to`, ошибки нет.\n\n**Кому доступен:** владельцу сообщества и сотрудникам с ролью «Админ (полный доступ)» или «Статистика».\n\n**Ошибки метода:**\n- `7` — канал не `VK`; дата не передана или неверная; период длиннее 90 дней; не передано ни одной метки; метка — не массив строк.\n- `8` — ни в одном вашем сообществе ВКонтакте у вас нет роли «Статистика».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал. Сейчас поддерживается только `VK` — ВКонтакте.", "example": "VK" }, "date_from": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Начало периода в формате `dd.mm.yyyy hh:ii` по московскому времени, например `01.09.2026 00:00`. Обязательный параметр.", "example": "01.01.2026 00:00" }, "date_to": { "type": "string", "pattern": "^\\d{2}\\.\\d{2}\\.\\d{4} \\d{2}:\\d{2}$", "description": "Конец периода в формате `dd.mm.yyyy hh:ii` по московскому времени — не позже чем через 90 дней после `date_from`. Обязательный параметр.", "example": "01.01.2026 00:00" }, "utm_source": { "type": "array", "items": { "type": "string" }, "description": "Какие значения метки `utm_source` искать. Передайте массив строк или строку, в которой записан JSON-массив, например `\"[\\\"vk_ads\\\"]\"`. Числа ищутся как строки.", "example": [ "vk_ads" ] }, "utm_medium": { "type": "array", "items": { "type": "string" }, "description": "Какие значения метки `utm_medium` искать. Передайте массив строк или строку, в которой записан JSON-массив, например `\"[\\\"vk_ads\\\"]\"`. Числа ищутся как строки.", "example": [ "vk_ads" ] }, "utm_campaign": { "type": "array", "items": { "type": "string" }, "description": "Какие значения метки `utm_campaign` искать. Передайте массив строк или строку, в которой записан JSON-массив, например `\"[\\\"vk_ads\\\"]\"`. Числа ищутся как строки.", "example": [ "vk_ads" ] }, "utm_content": { "type": "array", "items": { "type": "string" }, "description": "Какие значения метки `utm_content` искать. Передайте массив строк или строку, в которой записан JSON-массив, например `\"[\\\"vk_ads\\\"]\"`. Числа ищутся как строки.", "example": [ "vk_ads" ] }, "utm_term": { "type": "array", "items": { "type": "string" }, "description": "Какие значения метки `utm_term` искать. Передайте массив строк или строку, в которой записан JSON-массив, например `\"[\\\"vk_ads\\\"]\"`. Числа ищутся как строки.", "example": [ "vk_ads" ] }, "count": { "type": "integer", "default": 1000, "minimum": 1, "maximum": 1000, "description": "Сколько событий вернуть за один запрос. По умолчанию 1000, больше 1000 нельзя." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Сколько записей пропустить от начала списка. Так получают список по страницам: вторая страница по 100 записей — `count=100`, `offset=100`, третья — `offset=200`." } }, "required": [ "channel", "date_from", "date_to" ] }, "example": { "channel": "VK", "date_from": "01.01.2026 00:00", "date_to": "31.01.2026 23:59", "utm_source": [ "vk_ads" ], "count": 100 } } } }, "responses": { "200": { "description": "Сервер всегда отвечает с HTTP-кодом 200, даже при ошибке. Удался ли запрос, видно по полю `status`: `ok` или `error`. При ошибке её номер — в поле `error_code`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Успешный ответ", "required": [ "status", "response" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "response": { "type": "object", "properties": { "count": { "type": "integer", "description": "Сколько событий пришло в этом ответе" }, "total": { "type": "integer", "description": "Сколько всего событий подходит под условия — на всех страницах вместе" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdsEvent" } } } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "ok": { "summary": "Успешный ответ", "value": { "status": "ok", "response": { "count": 1, "total": 1, "items": [ { "type": "subscribe", "time": 1704067200, "group_id": 123456, "user": { "id": 789, "first_name": "Иван", "last_name": "Иванов" }, "subscription": { "id": "65a6e5f4c0e8f20012d3a111", "name": "Название подписки" }, "utms": { "utm_source": "vk_ads", "utm_campaign": "test_campaign", "utm_medium": "", "utm_content": "", "utm_term": "", "th_ad_id": "" } } ] } } }, "error": { "summary": "Ошибка 7", "value": { "status": "error", "error": "Необходимо указать хотя бы один utm параметр", "error_code": 7 } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Личный токен со страницы «Доступы и токены» (https://targethunter.ru/settings/access) с продуктом BotHunter или токен приложения, которому вы разрешили доступ к BotHunter. Передаётся в заголовке `Authorization: Bearer <токен>`." }, "apiKey": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Параметр `api_key` — для инструментов, где нельзя задать свой заголовок. В нём можно передать тот же токен TargetHunter, что и в `Authorization: Bearer` (начинается с `thp_`, `lhp_` или `tha_`). Прежний ключ со страницы https://targethunter.ru/settings (блок «Токен доступа») в v2 не принимается — только на прежнем адресе без версии (v1). Передавайте его в теле запроса: в JSON или в форме. В строке запроса он тоже работает, но адрес запроса вместе с ключом сохраняется в журналах." } }, "schemas": { "Channel": { "type": "string", "enum": [ "VK", "TG", "OK", "MAX", "CHAT", "AVITO" ], "description": "Канал — соцсеть, мессенджер или другая площадка, где работает сообщество: `VK` — ВКонтакте, `TG` — Telegram, `OK` — Одноклассники, `MAX` — MAX, `CHAT` — онлайн-чат, `AVITO` — Авито." }, "Error": { "type": "object", "title": "Ошибка", "required": [ "status", "error", "error_code" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "string", "description": "Описание ошибки для человека" }, "error_code": { "type": "integer", "enum": [ 1, 3, 4, 5, 6, 7, 8, 9, 101 ], "description": "Номер ошибки. Что он значит — в таблице кодов ошибок в начале описания." } } }, "Me": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Номер пользователя TargetHunter, которому принадлежит токен или ключ" }, "auth": { "type": "string", "enum": [ "bearer", "api_key" ], "description": "Способ входа: `bearer` — по токену TargetHunter (в заголовке или в `api_key`), `api_key` — по прежнему ключу, бывает только на прежнем адресе без версии (v1)" }, "client_id": { "type": "string", "nullable": true, "description": "Кому выдан токен: `personal` — личный токен, `thc_…` — приложение, которое вы подключили через вход в аккаунт TargetHunter (например, MCP BotHunter). При входе по прежнему ключу (только v1) — `null`." } } }, "Group": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере" }, "channel": { "$ref": "#/components/schemas/Channel" }, "name": { "type": "string", "description": "Название" }, "photo": { "type": "string", "nullable": true, "description": "Адрес картинки сообщества" }, "is_owner": { "type": "boolean", "description": "`true` — вы владелец, `false` — сотрудник" }, "archived": { "type": "boolean", "description": "Сообщество в архиве" }, "deactivated": { "type": "boolean", "description": "Сообщество отключено в BotHunter" } } }, "Employee": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID пользователя TargetHunter" }, "name": { "type": "string", "nullable": true, "description": "Имя в TargetHunter. `null`, если имени нет или сервис аккаунтов не ответил" }, "roles": { "type": "array", "description": "Роли сотрудника", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "admin", "mailer", "users", "integrations", "stat", "event", "dogs", "crm" ], "description": "Постоянный ключ роли. Сравнивайте роли по нему" }, "title": { "type": "string", "description": "Название роли, как в интерфейсе. Может поменяться" } } } } } }, "Bot": { "type": "object", "properties": { "id": { "type": "string", "description": "ID бота" }, "name": { "type": "string", "description": "Название" }, "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере" }, "channel": { "$ref": "#/components/schemas/Channel" }, "active": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` — бот включён, `0` — выключен" }, "archived": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` — бот в архиве" }, "activity_type": { "type": "string", "description": "Событие, которое запускает бота, например `message_new` — входящее сообщение" }, "create_at": { "type": "integer", "description": "Когда создан — unix-время (число секунд с 1 января 1970 года)" } } }, "BotDetails": { "allOf": [ { "$ref": "#/components/schemas/Bot" }, { "type": "object", "properties": { "public_id": { "type": "string", "nullable": true, "description": "Публичный ID шаблона" }, "can_share": { "type": "boolean", "description": "Бота можно передать как шаблон" }, "is_favorite": { "type": "boolean", "description": "Бот в избранном" }, "time_archived": { "type": "integer", "description": "Когда отправлен в архив — unix-время (число секунд с 1 января 1970 года); `0` — не в архиве" }, "activity_param": { "nullable": true, "description": "Настройки события, которое запускает бота" }, "subscription_ids": { "type": "array", "items": { "type": "string" }, "description": "Мини-лендинги, подписка на которые запускает бота" } } } ] }, "BotStep": { "type": "object", "properties": { "id": { "type": "string", "description": "ID шага. Его можно передать как `step_id` в `bots/addUser`" }, "title": { "type": "string", "description": "Название шага. У стартового шага — название события запуска, как в интерфейсе" }, "contain": { "type": "string", "nullable": true, "enum": [ "messages", "action", "if", "timer", "ai", null ], "description": "Вид шага: `messages` — сообщение, `action` — действие, `if` — условие, `timer` — таймер, `ai` — AI-блок. У стартового шага — `null`" }, "contain_name": { "type": "string", "nullable": true, "description": "Название вида шага в интерфейсе" }, "is_start": { "type": "boolean", "description": "Стартовый ли это шаг. С него `bots/addUser` запускает бота, если `step_id` не передан" } } }, "Mailing": { "type": "object", "properties": { "id": { "type": "string", "description": "ID рассылки" }, "title": { "type": "string", "description": "Название" }, "type": { "type": "integer", "enum": [ 3, 4, 5 ], "description": "`3` — целевая, `4` — разовая, `5` — по событиям" }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 7 ], "description": "`0` — ожидает отправки, `1` — отправляется, `2` — приостановлена, `3` — завершена, `4` — черновик, `7` — ожидает остановки" }, "status_name": { "type": "string", "description": "Название статуса, как в интерфейсе" }, "archived": { "type": "boolean", "description": "Завершённая рассылка в архиве" }, "date_send": { "type": "integer", "nullable": true, "description": "Когда отправка — unix-время (число секунд с 1 января 1970 года)" }, "count": { "type": "integer", "description": "Сколько сообщений обработано" }, "delivered": { "type": "integer", "description": "Доставлено" }, "no_delivered": { "type": "integer", "description": "Не доставлено" }, "create_at": { "type": "integer", "description": "Когда создана — unix-время (число секунд с 1 января 1970 года)" } } }, "MailingDetails": { "allOf": [ { "$ref": "#/components/schemas/Mailing" }, { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Номер сообщества в соцсети или мессенджере" }, "channel": { "$ref": "#/components/schemas/Channel" }, "message": { "type": "string", "description": "Текст сообщения" }, "attachments": { "type": "array", "description": "Вложения рассылки: ID и вид. Ссылку на файл вложения даёт метод `attachments/getById`", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID вложения — передайте его как `attachment_id` в `attachments/getById`" }, "type": { "type": "string", "description": "Вид вложения, например `photo`" } } } } } } ] }, "List": { "type": "object", "properties": { "id": { "type": "string", "description": "ID списка" }, "name": { "type": "string", "description": "Название" }, "count_users": { "type": "integer", "description": "Сколько подписчиков в списке" } } }, "ListUser": { "type": "object", "properties": { "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере" }, "name": { "type": "string", "description": "Имя" }, "added_at": { "type": "integer", "description": "Когда добавлен в список — unix-время (число секунд с 1 января 1970 года)" } } }, "Contact": { "type": "object", "properties": { "uid": { "type": "integer", "description": "Номер человека в соцсети или мессенджере" }, "name": { "type": "string", "nullable": true, "description": "Имя. Если его поменяли в карточке контакта — новое имя" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true, "description": "Короткое имя в соцсети или мессенджере" }, "phone": { "type": "string", "nullable": true, "description": "Телефон из карточки контакта в этом сообществе" }, "email": { "type": "string", "nullable": true, "description": "Почта из карточки контакта в этом сообществе" }, "create_at": { "type": "integer", "nullable": true, "description": "Когда подписчик появился в сообществе — unix-время (число секунд с 1 января 1970 года); `null`, если неизвестно" } } }, "ContactVariable": { "type": "object", "properties": { "id": { "type": "string", "description": "ID переменной. Его можно передать как `var_id` в методы `vars/*`" }, "title": { "type": "string", "description": "Название" }, "name": { "type": "string", "description": "Имя для подстановки в тексты: `{%name%}`" }, "value": { "type": "string", "nullable": true, "description": "Значение у подписчика. `null`, если значения нет" } } }, "ContactList": { "type": "object", "properties": { "id": { "type": "string", "description": "ID списка" }, "name": { "type": "string", "description": "Название" }, "added_at": { "type": "integer", "description": "Когда подписчик добавлен в список — unix-время (число секунд с 1 января 1970 года)" } } }, "ContactBot": { "type": "object", "properties": { "id": { "type": "string", "description": "ID бота" }, "name": { "type": "string", "description": "Название бота" }, "steps": { "type": "array", "description": "Шаги, на которых подписчик сейчас. Обычно шаг один. Если бот разрешает входить в него повторно, подписчик может проходить бота несколько раз одновременно — тогда и шагов несколько.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID шага" }, "title": { "type": "string", "description": "Название шага" }, "step_entered_at": { "type": "integer", "description": "Когда подписчик пришёл на шаг — unix-время (число секунд с 1 января 1970 года)" }, "bot_entered_at": { "type": "integer", "description": "Когда вошёл в бота — unix-время (число секунд с 1 января 1970 года)" } } } } } }, "Variable": { "type": "object", "properties": { "id": { "type": "string", "description": "ID переменной. Его можно передать как `var_id` в `vars/get`, `vars/set` и `vars/clear`" }, "title": { "type": "string", "description": "Название" }, "name": { "type": "string", "description": "Имя для подстановки `{%name%}` в текстах" }, "create_at": { "type": "integer", "description": "Когда создана — unix-время (число секунд с 1 января 1970 года)" } } }, "VariableValue": { "type": "object", "properties": { "title": { "type": "string", "description": "Название переменной" }, "name": { "type": "string", "description": "Имя для подстановки в тексты: `{%name%}`" }, "value": { "type": "string", "nullable": true, "description": "Значение. `null`, если его нет" } } }, "Landing": { "type": "object", "properties": { "id": { "type": "string", "description": "ID лендинга" }, "title": { "type": "string", "description": "Название" }, "kind": { "type": "string", "enum": [ "mini", "multichannel" ], "description": "`mini` — мини-лендинг, `multichannel` — мультиканальный лендинг" }, "url": { "type": "string", "description": "Адрес лендинга" }, "create_at": { "type": "integer", "description": "Когда создан — unix-время (число секунд с 1 января 1970 года)" } } }, "Funnel": { "type": "object", "properties": { "id": { "type": "string", "description": "ID воронки" }, "title": { "type": "string", "description": "Название" }, "create_at": { "type": "integer", "description": "Когда создана — unix-время (число секунд с 1 января 1970 года)" } } }, "FunnelStep": { "type": "object", "properties": { "id": { "type": "string", "description": "ID шага воронки" }, "type": { "type": "string", "description": "Вид шага, например `start`" }, "title": { "type": "string", "description": "Название" }, "count": { "type": "integer", "description": "Подписчиков на шаге" }, "cost": { "type": "number", "description": "Сколько стоит один подписчик на этом шаге. Считается из бюджета воронки" }, "values": { "type": "number", "description": "Ценность точек конверсии" }, "avg_value": { "type": "number", "description": "Ценность в расчёте на одного подписчика" }, "profit": { "type": "number", "description": "`avg_value` минус `cost`" }, "reach_percent": { "type": "string", "nullable": true, "description": "Какая доля подписчиков первого шага дошла до этого шага, строкой. У первого шага — `null`" }, "connects": { "type": "array", "items": { "type": "string" }, "description": "Следующие шаги" }, "connected_percents": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Какая доля подписчиков перешла в каждый следующий шаг, строкой" } } }, "FunnelDetails": { "type": "object", "properties": { "id": { "type": "string", "description": "ID воронки" }, "title": { "type": "string", "description": "Название" }, "budget": { "type": "number", "description": "Бюджет воронки" }, "budget_type": { "type": "string", "description": "Как задан бюджет" }, "source_only": { "type": "boolean", "description": "Считать только подписчиков из источника" }, "freeze_at": { "type": "integer", "nullable": true, "description": "Дата заморозки — unix-время (число секунд с 1 января 1970 года); `null` — воронка не заморожена" }, "create_at": { "type": "integer", "description": "Когда создана — unix-время (число секунд с 1 января 1970 года)" }, "counted_at": { "type": "integer", "description": "Когда посчитана статистика — unix-время (число секунд с 1 января 1970 года)" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FunnelStep" } } } }, "MailingChartItem": { "type": "object", "properties": { "date": { "type": "string", "description": "День строкой, например `1.1.2026`" }, "delivered": { "type": "integer", "description": "Доставлено" }, "not_delivered": { "type": "integer", "description": "Не доставлено" }, "reads": { "type": "integer", "description": "Прочитали" }, "clicks": { "type": "integer", "description": "Перешли по ссылке" } } }, "MailingChartTotal": { "type": "object", "description": "Суммы по всем дням графика за весь период", "properties": { "delivered": { "type": "integer" }, "not_delivered": { "type": "integer" }, "reads": { "type": "integer" }, "clicks": { "type": "integer" } } }, "LandingChartItem": { "type": "object", "properties": { "date": { "type": "string", "description": "День строкой, например `2026-01-01`" }, "subscribed": { "type": "integer", "description": "Подписались" }, "unsubscribed": { "type": "integer", "description": "Отписались" } } }, "AdsEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "subscribe", "unsubscribe" ], "description": "`subscribe` — подписка, `unsubscribe` — отписка" }, "time": { "type": "integer", "description": "Когда — unix-время (число секунд с 1 января 1970 года)" }, "group_id": { "type": "integer", "description": "Номер сообщества ВКонтакте" }, "user": { "type": "object", "description": "Подписчик — если он ещё существует", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "subscription": { "type": "object", "description": "Лендинг — если он ещё существует", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "utms": { "type": "object", "description": "UTM-метки события", "additionalProperties": { "type": "string" } } } }, "Attachment": { "type": "object", "properties": { "id": { "type": "string", "description": "ID вложения" }, "type": { "type": "string", "description": "Вид вложения, например `photo` — картинка, `doc` — документ" }, "title": { "type": "string", "description": "Имя файла. Если имени нет — название вида вложения, например «Изображение» или «Документ»" }, "url": { "type": "string", "nullable": true, "description": "Ссылка на файл, та же, что в интерфейсе BotHunter. `null`, если у вложения нет файла" } } }, "GlobalVariable": { "type": "object", "properties": { "id": { "type": "string", "description": "ID переменной. Его можно передать как `var_id` в `globalVars/get`, `globalVars/set` и `globalVars/clear`" }, "title": { "type": "string", "description": "Название" }, "name": { "type": "string", "description": "Имя для подстановки `{%name%}` в текстах" }, "value": { "type": "string", "nullable": true, "description": "Текущее значение. `null`, если его нет" }, "create_at": { "type": "integer", "description": "Когда создана — unix-время (число секунд с 1 января 1970 года)" } } } } } }