Боты

Подключение и управление Telegram-ботами, которые встречают подписчиков и отслеживают вступления в ваши чаты, а также правка профиля бота (имя, описание, аватар).

Все эндпоинты этого раздела требуют авторизации по вашему API-ключу (см. Профиль и API-ключ) и активной оплаченной подписки. Без подписки запрос вернёт ошибку unpaid; при отсутствии или недействительности ключа — key, для заблокированного аккаунта — ban.

Каждый ответ — это HTTP 200 с Content-Type: application/json. Успех или ошибка определяются полем status в теле, а не HTTP-кодом. Ошибка всегда приходит в виде {"status":"error","error":"<код>"}.

Список ботов

GET /api/bots/list.json

Возвращает подключённые к вашему аккаунту боты, отсортированные от новых к старым. Мягко удалённые боты (статус 3) в список не попадают. При открытии списка имена и @username ботов фоново синхронизируются с Telegram (не чаще одного прохода на пользователя раз в 5 минут), поэтому переименованный в Telegram бот подтянется без ручного переподключения.

{
  "status": "ok",
  "data": [
    {
      "id": 7,
      "tg": 7123456789,
      "username": "mytrackbot",
      "name": "My Tracking Bot",
      "status": 0,
      "created": 1746100800,
      "default_campaign": 0
    }
  ]
}

data — это массив (пустой [], если ботов нет). Поле created — Unix-время в секундах (целое число), а не строка с датой. Поле default_campaign — id кампании по умолчанию, запускаемой при открытии бота без кода кампании; 0 — не задана (тогда берётся новейшая активная кампания).

Подключить бота

POST /api/bots/add.json

Подключает бота по его токену из BotFather. Токен проверяется через Telegram API (getMe), хранится в зашифрованном виде, после чего регистрируется вебхук для приёма обновлений.

{
  "status": "ok",
  "data": {
    "id": 7,
    "tg": 7123456789,
    "username": "mytrackbot",
    "name": "My Tracking Bot"
  }
}

В ответе значимы поля id, tg, username и name; поля status и created здесь не заполняются.

Восстановление при повторном добавлении: если вы ранее отключили этого бота и добавляете тот же токен снова, существующая запись реактивируется (статус становится активным) — дубликат не создаётся, кампании бота сохраняются. Токен, уже привязанный к другому аккаунту, будет отклонён.

Список чатов с правами администратора

GET /api/bots/chats.json

Возвращает чаты, где бот является администратором (читается из кеша нашего бэкенда), исключая чаты, уже занятые вашей действующей кампанией (каждый чат можно использовать только в одной кампании). Используется как список выбора при создании кампании. Пустой список — нормальная ситуация (бот только что добавлен, нигде не администратор или все его чаты уже заняты).

{
  "status": "ok",
  "data": [
    { "id": -1001234567890, "title": "My Channel", "type": "channel" }
  ]
}

data — массив (пустой [] при промахе кеша или если все чаты уже заняты). Поле type — строковый тип чата Telegram (channel, group, supergroup). Кеш наполняется в момент, когда бот получает права администратора в чате; если ожидаемый чат отсутствует, убедитесь, что бот действительно администратор, и повторите запрос.

Кампании бота

GET /api/bots/campaigns.json

Возвращает кампании этого бота (кроме удалённых, от новых к старым) — список выбора для закрепления кампании по умолчанию.

{
  "status": "ok",
  "data": [
    { "id": 42, "name": "Летняя акция", "status": 0 }
  ]
}

data — массив (пустой [], если у бота нет кампаний). Поле status совпадает со статусом кампании (0 активна, 1 на паузе и т.д.).

Кампания по умолчанию

POST /api/bots/default.json

Закрепляет за ботом кампанию, которая запускается, когда подписчик открывает бота без кода кампании (обычный /start). Если кампания не закреплена, используется новейшая активная кампания бота. Закреплённая кампания должна быть одной из живых (неудалённых) кампаний этого бота.

{ "status": "ok" }

Закрепление носит подсказочный характер: если позже эту кампанию поставить на паузу или удалить, бот мягко вернётся к новейшей активной — переустанавливать поле не нужно.

Отключить бота

POST /api/bots/del.json

Мягко удаляет бота (статус 3), снимает вебхук в Telegram (по возможности) и очищает кеш. Запись сохраняется для истории; все лиды, журнал и статистика, ссылающиеся на этого бота, остаются. Бота можно подключить повторно — применяется логика «Восстановление при повторном добавлении».

{ "status": "ok" }

Профиль бота

GET /api/bots/profile.json

Возвращает профиль бота со стороны Telegram (имя, описание и краткое описание), запрашивая его напрямую из Bot API (getMyName, getMyDescription, getMyShortDescription). В базе эти поля не хранятся — источником истины является Telegram.

{
  "status": "ok",
  "data": {
    "name": "My Tracking Bot",
    "description": "Этот бот встречает новых подписчиков и отслеживает вступления.",
    "short_description": "Трекинг вступлений в Telegram"
  }
}

Сохранить профиль бота

POST /api/bots/profile.json

Сохраняет имя, описание и краткое описание бота, отправляя их в Telegram (setMyName, setMyDescription, setMyShortDescription). Новое имя также дублируется в запись бота, поэтому список ботов сразу отражает изменение.

{ "status": "ok" }

Аватар бота

POST /api/bots/photo.json

Принимает изображение в составе multipart-формы (поле file) и устанавливает его как фото профиля бота через Telegram (setMyProfilePhoto). Файл передаётся напрямую в Telegram и нигде не сохраняется. Допустимы JPEG, PNG или WEBP размером не более 5 МиБ. Запрос отправляется как multipart/form-data.

{ "status": "ok" }