API для интеграции

Страница описывает те части HTTP API, которые нужны внешним системам: отправка сообщения боту и получение ответа (этим пользуется iQChannels), получение токена и служебные адреса состояния. Административное API консоли (боты, пользователи, роли) описано в коде маршрутов и предназначено для самой консоли; при необходимости интеграции с ним обратитесь в поддержку.

Все адреса относительно внешнего адреса платформы (IQB_EXTERNAL_URL). Тело запросов и ответов в JSON.

Сообщение боту: Converse API

POST /api/v1/bots/<бот>/converse/<идентификатор клиента>
Content-Type: application/json

{"type": "text", "text": "Привет"}

• <бот> идентификатор бота, <идентификатор клиента> любая строка, по которой платформа различает клиентов: по ней хранится состояние диалога (текущий процесс и звено, переменные сессии и пользователя). Для одного клиента всегда передавайте одно и то же значение.
• Тело: type всегда text, text сообщение клиента. Нажатие кнопки передаётся как её название (условия переходов принимают и название, и значение кнопки).
• Ответ приходит, когда бот закончил отвечать, и содержит все его реплики:

{
  "responses": [
    {"type": "text", "text": "Здравствуйте! Это бот контакт-центра банка «НашБанк»."},
    {"type": "single-choice", "text": "Чем я могу вам помочь?",
     "choices": [{"title": "Проверить баланс", "value": "balance"}, {"title": "Заблокировать карту", "value": "block"}]}
  ]
}

Типы реплик: text (поле text, может содержать разметку Markdown при markdown: true), single-choice (text и choices с title и value), card и carousel (заголовок, подзаголовок, изображение, кнопки действий), image, file, dropdown. Команды для iQChannels приходят в реплике text дополнительными полями: operatorid, groupid, toqueue, categoryid (переадресация), closedialog (закрыть обращение).

Коды ответа:

Код	Когда	Что делать
200	Бот ответил	Показать реплики клиенту
400	Неверное тело: тип не text, пустой или слишком длинный текст	Исправить запрос
404	Бот не существует или отключён	Проверить идентификатор и состояние бота
503 с заголовком Retry-After	Узел перегружен (IQB_CONVERSE_MAX_IN_FLIGHT) или завершает работу	Повторить через указанное число секунд, в кластере балансировщик сам направит запрос на другой узел
504	Бот не ответил за converse.timeout (по умолчанию 5 секунд)	Сообщение принято и обработано, но ответ не сформирован вовремя: проверьте действия бота, которые ждут внешние системы

Отладочная версия: состояние и решения

POST /api/v1/bots/<бот>/converse/<клиент>/secured?include=nlu,state,suggestions,decision
Authorization: Bearer <токен>

Тот же запрос с токеном сотрудника дополнительно возвращает результат распознавания (nlu: намерение, уверенность, сущности), состояние диалога (state: temp, session, user, context), кандидатов на ответ (suggestions) и принятое решение (decision). Удобно для автоматических проверок и разбора инцидентов; клиентским системам эти данные не нужны.

Токен доступа

Токен нужен для /secured и для административного API. Он выдаётся на jwtToken.duration (по умолчанию час) и передаётся в заголовке Authorization: Bearer <jwt>; административные запросы дополнительно требуют заголовок X-BP-Workspace: <id рабочего пространства>.

POST /api/v2/admin/auth/login/basic/default
{"email": "integration@example.com", "password": "<секрет>"}

{"status": "success", "message": "Login successful", "payload": {"jwt": "<токен>", "exp": 3600000}}

Для интеграционной учётной записи (iQChannels) создайте пользователя с признаком интеграции в разделе «Пользователи»: его секрет не истекает и не требует смены при первом входе, второй фактор к нему не применяется. Стратегия ldap принимает тот же запрос по адресу /api/v2/admin/auth/login/ldap/<id>; единый вход OpenID Connect работает только через браузер.

Ошибки входа приходят с кодом 400 и полем errorCode: BP_0009 неверный логин или пароль, BP_0010 пароль истёк (нужно передать newPassword), BP_0011 учётная запись заблокирована, BP_0013 нужен код второго фактора (поле otp), BP_0015 неверный код. Лимит неудачных попыток: 30 за 15 минут с одного адреса (429).

Состояние узла

Адрес	Назначение
GET /status	Состояние компонентов (up/down/n/a), 200 пока узел готов, 503 при запуске и остановке
GET /health	200, если узел принимает трафик и компоненты работают, иначе 503 и список причин
GET /metrics	Метрики Prometheus, при заданном IQB_METRICS_TOKEN требует Authorization: Bearer
GET /version	Версия ядра

Подробнее в разделе Мониторинг.

Ограничения и рекомендации

• Один клиент, одно сообщение за раз: следующее сообщение отправляйте после получения ответа на предыдущее, иначе реплики могут перемешаться. В кластере балансировщик должен направлять сообщения одного клиента на один узел, см. Распределение нагрузки.
• Длина текста ограничена maxMessageLength настроек веб-чата (по умолчанию 360 символов).
• Converse API не хранит вложения: файлы передаются ссылками в тексте.
• Если включено ограничение запросов (httpServer.rateLimit), оно действует и на Converse API; для интеграции с iQChannels подберите лимит с запасом или отключите его.