Документация API и вебхуков

Мультиагентный ИИ-агент клиентской поддержки: REST API, вебхуки и способы интеграции с внешними информационными системами. Документ публичный, на русском языке, описывает работающий стенд, на котором вы сейчас находитесь.

Быстрый старт

Минимальная интеграция — один POST. Отправьте сообщение клиента, получите готовые к отправке сообщения и полную трассировку того, как ответ был получен.

curl -X POST https://HOST/api/message \
  -H 'Content-Type: application/json' \
  -d '{"dialog": "crm-42817", "text": "Сколько стоит тариф Оптимальный?"}'

{
  "диалог": "crm-42817",
  "сообщения": [
    "Тариф «Оптимальный» стоит 550 ₽ в месяц. В него входит 500 минут, 100 SMS и 20 ГБ интернета."
  ],
  "трасса": {
    "мс": 2840,
    "цена": 0.0217,
    "шаги": [ { "имя": "нормализация" }, { "имя": "арбитр", "сценарий": "тарифы" } ],
    "вызовы": [ { "роль": "арбитр", "модель": "GigaChat-Pro", "токеныВход": 412,
                  "токеныВыход": 38, "цена": 0.0068, "мс": 640, "версияПромпта": "1.0.0" } ],
    "фрагменты": [ { "путь": "Тарифы.xlsx › Тарифы › строка 3", "оценка": 0.86 } ]
  }
}

Поля запроса принимаются на двух языках. dialog и диалог, text и текст — равнозначны. В ответах имена полей русские.

Авторизация

Чтение и отправка сообщений открыты. Методы, меняющие базу знаний и состояние стенда, закрываются токеном: заголовок X-Admin-Token. Токен задаётся переменной окружения ADMIN_TOKEN; если она пуста, защита выключена — так стенд работает в демонстрационном режиме.

curl -X POST https://HOST/api/kb/reindex \
  -H 'X-Admin-Token: ваш-токен'

В промышленной установке API закрывается дополнительно на уровне сетевого контура и единого входа (SSO по OIDC или SAML), а все внешние соединения идут по TLS.

Форматы и коды ошибок

• Кодировка — UTF-8. Тела запросов и ответов — application/json, кроме загрузки файла и выгрузки XLSX.
• Идентификатор диалога dialog задаёте вы: это ключ, по которому хранится контекст. Удобно передавать идентификатор обращения из вашей системы.
• Ошибка — код HTTP и тело {"ошибка": "текст"}.

Диалог

Обработать сообщение клиента. Синхронный: возвращает сообщения, готовые к отправке в канал.

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

Список диалогов: этап, сценарий, категория, оценка CSI, число эскалаций.

Полная карточка диалога: все сообщения, события журнала аудита и вызовы модели по этому диалогу. Это и есть трассировка ответа: по любому сообщению видно, какие фрагменты базы знаний использовались, какая модель отвечала, какая версия промпта применялась и сколько это стоило.

Сообщить, что в диалог вошёл сотрудник. Агент немедленно замолкает и не отправляет сообщения, пока его не вернут. Вызывайте из операторского пульта.

{ "dialog": "crm-42817", "staff": "Иванова А.", "enable": true }

enable: false возвращает агента в диалог.

База знаний

Состав базы: документы, выбранный режим нарезки, число фрагментов, листы и колонки таблиц, добавленные веб-страницы, история перестроек индекса.

Загрузить или заменить файл. Тело запроса — сырые байты файла, без multipart. Поддерживаются XLSX, XLS, CSV, TSV, PDF, MD, TXT. Прежняя редакция уходит в архив, индекс пересобирается автоматически. Требует X-Admin-Token.

curl -X POST 'https://HOST/api/kb/file?name=Тарифы.xlsx' \
  -H 'X-Admin-Token: ваш-токен' \
  --data-binary @Тарифы.xlsx

Удалить файл и пересобрать индекс. Требует токен.

Настроить индексацию файла: режим нарезки и — для таблиц — какие колонки участвуют в поиске, а какие попадают в ответ клиенту. Требует токен.

{
  "файл": "Тарифы.xlsx",
  "настройки": {
    "режим": "строки таблицы",
    "Тарифы": {
      "колонкиПоиска": ["Тариф", "Кому подходит"],
      "колонкиОтвета": ["Тариф", "Абонентская плата", "Минуты на все номера", "Интернет, ГБ"]
    }
  }
}

Режимы нарезки: целиком, разделы, смысловые фрагменты, строки таблицы. Если режим не задан, он выбирается автоматически по структуре документа.

Добавить страницу сайта: {"url": "https://…"}. Содержимое очищается от навигации, футеров и скриптов. Дедупликация по канонической ссылке и по хешу текста — та же статья по другому адресу дубликат не создаст. Требует токен.

Пересобрать индекс. Сборка идёт рядом с действующим индексом и подменяет его одной операцией: во время переиндексации агент продолжает отвечать по прежней версии. Требует токен.

Поиск

Тот же поиск, которым пользуется агент. Полезен для отладки базы знаний и для интеграции поиска в ваши интерфейсы.

{ "query": "сколько стоит тариф", "threshold": 0.45, "limit": 8 }

В ответе — отобранные фрагменты с оценкой и разбором: место в полнотекстовом и векторном списках, покрытие запроса, косинусная близость, BM25. Поле достаточно показывает, стал бы агент отвечать по этим данным или ушёл бы к эксперту.

Как устроен поиск. Параллельно работают векторный семантический поиск и полнотекстовый с русской морфологией (стеммер Портера, BM25). Результаты объединяются методом Reciprocal Rank Fusion и переранжируются по признакам. Ниже порога релевантности генерация не запускается вовсе — вместо выдуманного ответа агент задаёт уточняющий вопрос или обращается к эксперту.

Эксперт

Очередь вопросов, на которые не нашлось подтверждённого ответа, и список уже подтверждённых знаний.

Ответ эксперта. Доставляется клиенту в тот же диалог и сохраняется как подтверждённое знание: следующий похожий вопрос агент закрывает сам.

{ "id": "q1a2b3c4", "answer": "Для дачи подойдёт тариф «Только интернет».", "expert": "Иванова А." }

Метрики

Витрина показателей за период: доля автоматизации, FCR, AHT, время первого ответа со средним и перцентилями 50/75/90/95/99, CSI, CSAT, NPS, доля эскалаций, распределение по категориям, стоимость по моделям и по агентским ролям, стоимость одного автоматизированного обращения.

Та же выгрузка книгой Excel: лист показателей и лист диалогов. Готовится системой автоматически, ручная подготовка выгрузок не требуется.

Служебные

Состояние: режим работы модели, подключён ли MAX, сводка по индексу, версия промптов, текущие настройки, число вопросов в очереди эксперта.

Настройки на лету: порог релевантности, обезличивание персональных данных, csi (автозамер оценки), максСообщений в одном ответе.

Список правил программного фильтра промпт-инъекций с весами.

Проверка связи с Bot API мессенджера MAX по настроенному токену.

Исходящие вебхуки

Система сама сообщает вашим системам о событиях. Адрес приёмника задаётся переменной WEBHOOK_URL, общий секрет — WEBHOOK_SECRET.

Запрос: POST, Content-Type: application/json, заголовки X-Agent-Event (тип события) и X-Agent-Signature — sha256=HMAC_SHA256(секрет, сырое тело). Проверяйте подпись до разбора тела.

{
  "тип": "эскалация",
  "время": "2026-09-11T08:14:22.417Z",
  "данные": { "диалог": "crm-42817", "сценарий": "тарифы", "мс": 3120, "цена": 0.0184,
              "эксперт": "q1a2b3c4" }
}

Доставка с повторами: три попытки с нарастающей паузой. Недоступность вашего приёмника не влияет на ответ клиенту.

Входящие вебхуки

Приём обновлений от Bot API мессенджера MAX. Отвечает немедленно, обработка асинхронная. Альтернатива длинному опросу.

Сигнал от операторского пульта: сотрудник вошёл в чат. Агент замолкает.

{ "chat_id": 918273, "staff": "Иванова А.", "enable": true }

Мессенджер MAX

Коннектор поддерживает оба режима: длинный опрос GET /updates и приём вебхуков. Токен бота задаётся переменной MAX_TOKEN, базовый адрес — MAX_API.

Что делает коннектор: принимает входящие сообщения, отправляет исходящие, ведёт сессии и контекст диалога, принимает голосовые сообщения и файлы, отправляет файлы из базы знаний, определяет вмешательство сотрудника и ставит агента на паузу.

Адаптация под мессенджер выполняется программно, а не моделью: длинный ответ режется по границам предложений на несколько коротких сообщений, списки разворачиваются в простой текст, Markdown-разметка снимается. После преобразования сверяются числа исходного и итогового текста: если хоть одно потерялось, отправляется исходный вариант одним сообщением. Красиво нарезанная неправда хуже некрасивой правды.

Способы интеграции с внешними системами

1. Через мессенджер. Токен бота — и агент работает в канале сам. Ваши системы не участвуют.
2. Синхронно через /api/message. Ваш контакт-центр, чат на сайте или мобильное приложение отправляют текст и получают готовые сообщения. Подходит, когда каналом владеете вы.
3. Асинхронно через вебхуки. Вы подписываетесь на события и складываете их в свою аналитику, CRM или хранилище.
4. Пультом оператора. /api/operator и /max/operator дают вашему рабочему месту оператора управление паузой агента.
5. Наполнением базы знаний. /api/kb/file и /api/kb/page позволяют обновлять знания из вашего портала или системы документооборота по расписанию.
6. Выгрузкой метрик. /api/metrics и /api/metrics.xlsx забираются вашей BI-системой без участия исполнителя.

Переменные окружения

Имена латинские: в systemd и в shell кириллические имена переменных молча не работают.

Ограничения и особенности

• Входящее сообщение обрезается до 4000 символов; невидимые символы и подмена кириллицы латиницей снимаются до всякой обработки.
• Загрузка файла в базу знаний — до 25 МБ на запрос.
• PDF без текстового слоя не индексируется: система сообщает об этом предупреждением, а не кладёт в индекс пустышку. Для сканов нужен OCR.
• Персональные данные заменяются на суррогаты вида [ТЕЛЕФОН_1] до передачи в модель и восстанавливаются в ответе. Таблица соответствия живёт только в памяти обработчика запроса.
• Ответ клиенту формируется исключительно из фрагментов базы знаний. Числа, которых нет ни в одном отобранном фрагменте, считаются выдумкой, и такой ответ возвращается на переработку программной проверкой.
• Схемы данных и промпты версионируются; версия промпта попадает в журнал вместе с ответом.

Разработчик — ИП Глебова Ю. С., ИНН 862002268649. Документация описывает работающий стенд и обновляется вместе с ним. Вопросы по интеграции: 0704777eag@gmail.com.