Бот поддержки

API поддержки (тикеты)

База: https://api.bot-t.com

Все методы — POST, тело JSON, заголовок Content-Type: application/json.

Авторизация владельца бота: query-параметр token (токен бота) или secretKey. В теле почти всегда нужен bot_id.

Премиум-тариф для методов ниже не нужен, кроме ответа через /ticket-message/api-write (тариф «Расширенный» и выше).

Формат ответа

Успех:

{ "result": true, "data": ... }

Ошибка:

{ "result": false, "message": "текст ошибки" }

Булевы методы (change-status категории, массовые операции) возвращают data строкой: "1" — успех.

Исключение: поиск по названию тикета при успехе отдаёт { "results": [...] } без обёртки result/data.

Идентификаторы

Поле	Что это
`bot_id`	ID бота в BOT-T
`id` (в методах категорий)	ID поддержки. Совпадает с `bot_id`
`category_id`	ID категории
`ticket_id`	ID тикета
`user.id`	ID пользователя в системе. Это не Telegram ID
`implementer.id`	ID записи исполнителя в категории. Нужен только чтобы включить/выключить или удалить исполнителя
`user_id`, `implementer_id`, `manager_id`, `changing_id` в методах тикета и сообщений	ID пользователя (`user.id`), не `implementer.id`

Тикеты нельзя создать через API. Их открывает пользователь в Telegram-боте. API управляет категориями, исполнителями, уже существующими тикетами и ответами в них.

1. Категории

Категория — тематика тикетов («Техподдержка», «Оплата» и т.д.). Лимит категорий зависит от тарифа бота.

При создании категории владелец бота сразу добавляется исполнителем.

Список

POST /v1/support/category/index

curl -X POST "https://api.bot-t.com/v1/support/category/index?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "id": 1}'

Поле	Обязательно	Описание
`bot_id`	да	ID бота
`id`	да	ID поддержки (= `bot_id`)

data — массив категорий.

Создать

POST /v1/support/category/create

curl -X POST "https://api.bot-t.com/v1/support/category/create?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "id": 1, "title": "Техподдержка"}'

Поле	Обязательно	Описание
`bot_id`	да	ID бота
`id`	да	ID поддержки
`title`	да	Название

data — полный список категорий после создания.

Ошибка при превышении лимита тарифа: Превышен лимит кол-ва категорий в боте.

Переименовать

POST /v1/support/category/update-title

curl -X POST "https://api.bot-t.com/v1/support/category/update-title?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "title": "Оплата"}'

data — новое название (строка).

Включить / выключить

POST /v1/support/category/change-status

Переключает статус: активна ↔ неактивна. В выключенную категорию пользователь не может открыть тикет.

curl -X POST "https://api.bot-t.com/v1/support/category/change-status?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10}'

data: "1".

Удалить

POST /v1/support/category/delete

curl -X POST "https://api.bot-t.com/v1/support/category/delete?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "id": 1, "category_id": 10}'

data — список оставшихся категорий. Тикеты удалённой категории снимаются отдельно (может занять время).

Лог категории

POST /v1/support/category/log

curl -X POST "https://api.bot-t.com/v1/support/category/log?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "id": 1, "category_id": 10}'

Без category_id или с 0 — лог всех категорий поддержки.

data.items — события: время, тип, текст, кто сделал.

Объект категории

{
  "id": 10,
  "title": "Техподдержка",
  "status": 1,
  "default": 0,
  "view_category_id": 100,
  "telegram_chat_id": null
}

Поле	Описание
`id`	ID категории
`title`	Название
`status`	`1` — активна, `0` — выключена
`default`	`1` — категория по умолчанию
`view_category_id`	ID шаблона сообщения категории
`telegram_chat_id`	Telegram-чат для уведомлений; `null` — в личку менеджерам

Исполнители категории

Исполнитель обрабатывает тикеты категории. Чтобы отвечать в тикете, пользователь должен быть активным исполнителем этой категории.

Лимит исполнителей в категории зависит от тарифа.

Список

POST /v1/support/implementer/index

curl -X POST "https://api.bot-t.com/v1/support/implementer/index?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "limit": 20, "offset": 0}'

Количество

POST /v1/support/implementer/count

Тело: bot_id, category_id. data — число строкой.

Добавить

POST /v1/support/implementer/create

user_id — ID пользователя в системе (user.id).

curl -X POST "https://api.bot-t.com/v1/support/implementer/create?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "user_id": 121234}'

data — список исполнителей категории.

Ошибка при лимите: Превышен лимит кол-ва менеджеров категории.

Включить / выключить приём тикетов

POST /v1/support/implementer/change-status

Здесь implementer_id — это id записи исполнителя, не user.id.

curl -X POST "https://api.bot-t.com/v1/support/implementer/change-status?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "implementer_id": 55}'

status исполнителя: 1 — получает новые тикеты, 0 — нет.

Удалить из категории

POST /v1/support/implementer/delete

implementer_id — снова id записи исполнителя.

curl -X POST "https://api.bot-t.com/v1/support/implementer/delete?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "implementer_id": 55}'

Объект исполнителя

{
  "id": 55,
  "category_id": 10,
  "status": 1,
  "user": {
    "id": 121234,
    "telegram_id": 182352323552,
    "username": "manager",
    "first_name": "Иван",
    "last_name": "",
    "link": "...",
    "type": "private"
  }
}

2. Тикеты

Тикет открывает пользователь в боте. Через API можно смотреть, переименовывать, менять статус, исполнителя, категорию и удалять.

Статусы

Код	Смысл
1	Закрыт
2	Открыт (в работе)
3	Ожидает закрытия
4	Повторно открыт
5	Ожидает менеджера

Через change-status можно поставить только 2, 1 или 3.

Список по категории

POST /v1/support/ticket/index

curl -X POST "https://api.bot-t.com/v1/support/ticket/index?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "limit": 20, "offset": 0, "phase": "active"}'

Поле	Обязательно	Описание
`bot_id`	да	ID бота
`category_id`	да	Категория
`limit`	да	Размер страницы
`offset`	да	Смещение
`phase`	нет	`active` — ожидают менеджера и в работе; `closed` — закрытые и ожидающие закрытия; без `phase` — все сразу

Все тикеты бота

POST /v1/support/ticket/index-all

curl -X POST "https://api.bot-t.com/v1/support/ticket/index-all?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "limit": 20, "offset": 0}'

Количество в категории

POST /v1/support/ticket/count

Тело: bot_id, category_id. data — число строкой.

Один тикет

POST /v1/support/ticket/get-ticket

curl -X POST "https://api.bot-t.com/v1/support/ticket/get-ticket?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123}'

data — объект тикета (без полной переписки, только last_message).

По автору

POST /v1/support/ticket/search-author

user_id — автор тикета (user.id). category_id — любая категория этого бота (нужна для привязки к поддержке).

curl -X POST "https://api.bot-t.com/v1/support/ticket/search-author?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "user_id": 121234, "category_id": 10, "limit": 20, "offset": 0}'

По названию

POST /v1/support/ticket/search-title

Успешный ответ без result:

{ "results": [{ "id": "123", "title": "Тикет №2" }] }

Если совпадений нет: { "results": [{ "id": "", "title": "" }] }.

curl -X POST "https://api.bot-t.com/v1/support/ticket/search-title?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "support_id": 1, "title": "Тикет №", "limit": 10}'

Поле	Обязательно	Описание
`bot_id`	да	ID бота
`support_id` или `id`	да	ID поддержки (= `bot_id`)
`title`	да	Подстрока названия
`limit`	нет	По умолчанию 10

Переименовать

POST /v1/support/ticket/update-title

curl -X POST "https://api.bot-t.com/v1/support/ticket/update-title?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "title": "Оплата заказа 42"}'

data — новое название.

Сменить статус

POST /v1/support/ticket/change-status

implementer_id — user.id исполнителя, который совершает действие. Он должен быть активным исполнителем категории.

curl -X POST "https://api.bot-t.com/v1/support/ticket/change-status?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "implementer_id": 121234, "status": 2}'

`status`	Действие
`2`	Взять в работу (исполнитель становится менеджером тикета)
`3`	Предложить закрыть
`1`	Закрыть

data — обновлённый тикет. Другие коды статуса — ошибка status not valid.

Назначить исполнителя

POST /v1/support/ticket/change-manager

curl -X POST "https://api.bot-t.com/v1/support/ticket/change-manager?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "manager_id": 121234, "changing_id": 121235}'

Поле	Описание
`manager_id`	Кому передают (`user.id`)
`changing_id`	Кто передаёт (`user.id`)

Оба должны быть пользователями этого бота.

Перенести в другую категорию

POST /v1/support/ticket/move-category

curl -X POST "https://api.bot-t.com/v1/support/ticket/move-category?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "category_id": 11, "user_id": 121234}'

category_id — категория, куда переносят. user_id — кто переносит. data — тикеты целевой категории.

Массово передать незакрытые тикеты категории

POST /v1/support/ticket/mass-transfer

Переносит открытые / повторно открытые / ожидающие закрытия тикеты категории на исполнителя.

curl -X POST "https://api.bot-t.com/v1/support/ticket/mass-transfer?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "implementer_id": 121234, "changing_id": 121235}'

data: "1".

Массово предложить закрыть

POST /v1/support/ticket/mass-offer

Предложение о закрытии всем открытым тикетам категории.

curl -X POST "https://api.bot-t.com/v1/support/ticket/mass-offer?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "category_id": 10, "implementer_id": 121234}'

data: "1".

Удалить тикет

POST /v1/support/ticket/delete

curl -X POST "https://api.bot-t.com/v1/support/ticket/delete?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123}'

data — оставшиеся тикеты категории.

Лог тикета

POST /v1/support/ticket/log

curl -X POST "https://api.bot-t.com/v1/support/ticket/log?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123}'

data.items — события по тикету.

Объект тикета

{
  "id": 123,
  "category_id": 10,
  "title": "Тикет №2",
  "status": 2,
  "user": {},
  "manager": {},
  "last_message": {},
  "created_at": "2023-10-13 20:47",
  "accepted_at": "2023-10-13 20:50",
  "closed_at": null,
  "deleted_at": null,
  "offered_at": null
}

Даты тикета — в часовом поясе бота, формат Y-m-d H:i. user — автор, manager — текущий исполнитель.

3. Сообщения и ответы

Прочитать переписку

POST /v1/support/ticket-message/get-messages

Отдельного метода «все сообщения одним запросом без лимита» нет — нужна пагинация.

История (offset + limit): на странице сообщения от старых к новым. limit обязателен. Крутите offset, пока data не пустой.

curl -X POST "https://api.bot-t.com/v1/support/ticket-message/get-messages?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "limit": 100, "offset": 0}'

Инкремент (after_id или since_id): сообщения с id больше указанного, по возрастанию. limit необязателен (по умолчанию 50, максимум 100). Начните с after_id: 0, затем подставляйте id последнего элемента, пока длина data меньше limit.

curl -X POST "https://api.bot-t.com/v1/support/ticket-message/get-messages?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "after_id": 0, "limit": 100}'

Поле	Обязательно	Описание
`bot_id`	да	ID бота
`ticket_id`	да	ID тикета
`limit`	да, если нет `after_id`	Размер страницы
`offset`	нет	Смещение истории
`after_id` / `since_id`	нет	Только сообщения новее этого id

Ответить от текущего менеджера

POST /v1/support/ticket-message/implementer-write

У тикета уже должен быть менеджер. implementer_id обязан совпадать с manager.id тикета.

Нужен текст и/или медиа. HTML в тексте срезается.

curl -X POST "https://api.bot-t.com/v1/support/ticket-message/implementer-write?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "implementer_id": 121234, "text": "Здравствуйте, уже смотрим."}'

С файлом из хранилища бота (файл уже загружен в менеджер файлов):

{
  "bot_id": 1,
  "ticket_id": 123,
  "implementer_id": 121234,
  "text": "Скриншот",
  "media_path": "photos",
  "media_link": "abc123.jpg"
}

Поле	Обязательно	Описание
`bot_id`	да	ID бота
`ticket_id`	да	Тикет
`implementer_id`	да	`user.id` текущего менеджера тикета
`text`	да, если нет медиа	Текст
`media_path`	вместе с `media_link`	`photos`, `files` или `videos`
`media_link`	вместе с `media_path`	Имя файла в хранилище бота (только имя, не путь)

data — массив из одного созданного сообщения.

Типичные ошибки: ticket_id not found, text or media not found, implementer_id not found, access (не менеджер тикета), unsupported media path. Если менеджера нет — текст вроде «сначала возьмите тикет в работу».

Ответить по API (интеграции)

POST /v1/support/ticket-message/api-write

Нужен тариф «Расширенный» и выше. Иначе: AI-агент поддержки доступен с тарифа «Расширенный».

implementer_id — активный исполнитель категории (user.id):

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

implementer_id можно не передавать, если менеджер уже назначен — возьмётся он.

Тело как у implementer-write (текст и/или медиа). Ответ — массив из созданного сообщения.

curl -X POST "https://api.bot-t.com/v1/support/ticket-message/api-write?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "ticket_id": 123, "implementer_id": 121234, "text": "Ответ из внешней системы"}'

Что выбрать для ответа

Метод	Когда
`implementer-write`	Тикет уже в работе, отвечаете от его менеджера
`api-write`	Внешняя система / бот: можно автоназначить исполнителя категории. Нужен тариф «Расширенный»+

Пользователь отвечает только в Telegram, отдельного API «написать от пользователя» нет.

Объект сообщения тикета

{
  "id": 10,
  "ticket_id": 123,
  "author": "implementer",
  "user": {},
  "message": {
    "id": 500,
    "text": "Здравствуйте, уже смотрим."
  },
  "created_at": "2023-10-13 20:47:35"
}

Поле	Описание
`id`	ID сообщения в тикете
`ticket_id`	Тикет
`author`	`user` — клиент, `implementer` — исполнитель
`user`	Автор
`message`	Контент. Текст — `message.text`; могут быть фото, файл, видео
`created_at`	Дата в поясе бота, `Y-m-d H:i:s`

Выгрузка всей переписки

POST /v1/support/ticket/export

Пагинация по тикетам. В каждом элементе messages — все сообщения этого тикета, от старых к новым. Фильтра по одному ticket_id нет.

curl -X POST "https://api.bot-t.com/v1/support/ticket/export?token=BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "limit": 20, "offset": 0}'

Для одного тикета удобнее get-messages с циклом по after_id. Для дампа всех тикетов бота — export с циклом по offset.

Типовой сценарий

Создать категорию → добавить исполнителей (user.id).
Пользователь открывает тикет в боте.
Список: /ticket/index с phase: "active".
Взять в работу: /ticket/change-status со status: 2.
Ответить: /ticket-message/implementer-write или /ticket-message/api-write.
Закрыть: status: 3 (предложить) или status: 1 (закрыть).