API

Как устроен API BotHunter версии v2: адреса методов, запросы POST с JSON, вход по личному токену, формат ответа и общие коды ошибок.

Обновлено

API BotHunter позволяет из своего кода работать с сообществами, ботами, рассылками, списками, подписчиками и переменными.

Актуальная версия — v2

Актуальная версия API — v2. Каждый метод вызывается по своему адресу: https://bot-api.targethunter.ru/external-api/v2/{раздел}/{метод}. Например, список ботов — https://bot-api.targethunter.ru/external-api/v2/bots/get.

Отправляйте запросы методом POST, а параметры передавайте в теле запроса в формате JSON. Форма и параметры в адресе запроса тоже работают.

Прежние адреса продолжают работать для старых интеграций: адрес без версии https://bot-api.targethunter.ru/external-api/{раздел}/{метод} и https://smm.targethunter.ru/api/{раздел}/{метод} (он же https://bot.targethunter.ru/api/...). Для новых интеграций используйте v2.

Вход по личному токену

Каждый запрос должен показать, от чьего имени он отправлен. Для этого нужен личный токен — длинная строка, которая заменяет логин и пароль.

  1. Откройте страницу «Доступы и токены».

  2. Выпустите токен и выберите для него продукт BotHunter.

  3. Выберите срок действия: 30 дней, 1 год или без срока. Для постоянной интеграции подойдёт «без срока».

  4. Сразу скопируйте токен и сохраните его: целиком он показывается только один раз.

Передайте токен в заголовке запроса: Authorization: Bearer <токен>. Если задать заголовок нельзя, передайте токен в параметре api_key в теле запроса. Прежний ключ API тоже работает, но поддерживает только методы из версии ниже v2 — подробнее на странице API Ключ.

Проверить токен можно методом users/me:

curl -X POST https://bot-api.targethunter.ru/external-api/v2/users/me \
  -H "Authorization: Bearer <ваш_токен>"

Если в ответе "status": "ok", токен работает.

Общие правила

  • Сообщество задают два параметра: group_id — номер сообщества в канале и channel — сам канал (константы). Оба приходят в ответе groups/get.

  • ID ботов, рассылок, списков, переменных, воронок и лендингов — строка из 24 символов. Берите их из ответов методов со списками.

  • uid — номер человека в соцсети или мессенджере, например id страницы ВКонтакте.

  • Списки приходят по страницам: count — сколько записей вернуть (по умолчанию 100, не больше 500), offset — сколько пропустить. Вторая страница по 100 записей — count=100, offset=100, третья — offset=200. В total — сколько записей всего.

  • Даты в запросах — в формате dd.mm.yyyy hh:ii по московскому времени. Время в ответах — unix-время (число секунд с 1 января 1970 года).

Ответ и ошибки

Сервер всегда отвечает с HTTP-кодом 200 — даже при ошибке. Удался ли запрос, видно по полю status: ok или error. Данные лежат в поле response. У методов, которые только выполняют действие, ответ — просто {"status": "ok"}.

При ошибке приходит {"status": "error", "error": "описание", "error_code": 7}: в error — текст ошибки, в error_code — её номер.

Общие коды ошибок

Код

Что значит

1

Не указан раздел или метод, такого раздела нет или в адресе неизвестная версия

3

В разделе нет такого метода

4

Токен или ключ не передан или не подходит: токен истёк, отозван или выпущен не для BotHunter

5

Слишком много запросов — больше 30 в секунду. Подождите немного и повторите запрос

6

Метод не смог выполнить действие — причина в поле error

7

Не передан обязательный параметр или он неверный, или объект с таким ID не найден. Объект чужого сообщества считается ненайденным

8

Нет доступа к сообществу или разделу: вы не владелец и не сотрудник сообщества или у вас нет нужной роли

9

Сервис проверки ключа временно недоступен — повторите запрос чуть позже

101

Внутренняя ошибка сервера

Справочник для разработчиков

Все методы v2 с параметрами, примерами запросов и ответов собраны в справочнике для разработчиков.

Разделы методов

Прежнее описание API — устарело, оставлено для старых интеграций.