Перейти к основному содержимому

Chat API

JAICP предоставляет Chat API — REST API для интеграции бота в сторонние приложения. С помощью Chat API вы можете встроить чат с ботом, например, в мобильное приложение, сайт или игру.

Перед началом работы с Chat API необходимо подключить к проекту канал Chat API и получить из настроек канала его токен, который используется в запросах ко всем методам.

подсказка
Подробнее о методах, параметрах запроса, форматах ответов и возвращаемых ошибках см. в спецификации Chat API.

Методы API​

Отправка запросов клиента в чат​

Синхронная отправка​

Предоставляются следующие методы для синхронной отправки запроса клиента:

  • POST /chatapi/{token}

    Метод возвращает подробную информацию о запросе, в том числе cid.

    Опциональное поле cid — идентификатор соединения. Это произвольная строка, определяющая текущее соединение с чат-приложением. Она может быть далее использована при получении событий в чате, чтобы фильтровать только события во время данного соединения.

  • GET /chatapi/{token}

    Упрощенный метод, который возвращает несколько параметров запроса: clientId, query и event.

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

Асинхронная отправка​

Метод POST /chatapi/{token}/async позволяет асинхронно отправлять запрос клиента или событие в чат-приложении. В отличие от метода POST /chatapi/{token} в ответ на запрос вы получите только идентификатор сообщения. Остальная информация будет отправлена на вебхук, который вы можете указать в настройках канала Chat API.

Событие будет отправлено на вебхук, если:

  • Вы отправили асинхронный запрос.
  • Вы провели рассылку.
  • Клиент получил ответ от оператора.
  • Время ожидания между ответами на запрос было превышено.
предупреждение
Если запрос не был успешно выполнен, запрос будет отправлен повторно еще три раза. Время ожидания между ответами при асинхронных запросах составляет три секунды.

На вебхук придет массив JSON-объектов:

{
    "token": "token",
    "clientId": "test",
    "questionId": "12345",
    "data": {
        "nlpClass": "/CatchAll",
        "confidence": -0.010999999999999979,
        "replies": [ // Сообщение бота
            {
                "type": "text",
                "text": "Скажите боту что-то осмысленное",
                "state": "/CatchAll"
            }
        ],
        "answer": "Скажите боту что-то осмысленное",
        "newSessionStarted": false,
        "debugData": [],
        "endSession": false
    },
    "timestamp": "2022-09-28T12:32:13.262",
    "blockForm": false
}

Расширение ответов настраиваемыми полями​

Вы можете расширить ответ бота с помощью настраиваемых полей. Используйте в сценарии объект $response:

state: ...
    script:
        $response.foo = "bar";

Поле foo и другие поля, которые вы зададите, будут доступны в ответе бота как вложенные в поле data.

Получение асинхронных событий в чате​

Метод GET /chatapi/{token}/events предназначен для получения асинхронных событий от сервера, например:

  • Ответ от оператора.
  • Изменение состояния виджета на другой странице браузера.
  • Запрос клиента, отправленный на другой странице.
  • Ответ бота на запрос с другой страницы.
предупреждение
Метод реализует стратегию long polling: если нет подходящих событий, он блокируется в ожидании следующего события.

Максимальное количество событий в ответе на запрос — 250. Если нужно обработать больше, используйте метод для получения истории переписки.

Фильтрация событий​

Параметр all данного метода определяет, нужно ли выводить все события в канале или только ответы от оператора (поведение по умолчанию).

предупреждение
Если клиент вел диалог в нескольких чатах одновременно, при выводе всех событий в канале и при отсутствии в запросе параметра cid метод может возвращать дубликаты сообщений.

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

Получение истории переписки​

Метод GET /chatapi/{token}/client/{clientId}/history позволяет получить историю переписки с клиентом за указанный период либо за все доступное время.

Сохранение и загрузка состояния чат-приложения​

Следующие методы позволяют сохранить и загрузить состояние чат-приложения во время диалога с клиентом:

подсказка
В теле запроса к методу POST передается произвольный объект. Последующий запрос к методу GET вернет ранее переданный объект. Его содержимое не проверяется.

Управление статусами сообщений​

Вы можете просматривать статусы сообщений, которые бот отправил в канале Chat API.

В Chat API поддерживаются следующие статусы сообщений:

СтатусChat API
ОтправленоSENT
ДоставленоDELIVERED
ПрочитаноREAD
Не отправленоNOT_SENT

Получение статуса сообщения​

Метод GET /chatapi/{token}/client/{clientId}/message/{questionId}/status позволяет получить статус сообщения.

Параметры:

  • token — токен канала Chat API. Перейдите в раздел Каналы, выберите канал Chat API и нажмите  → Редактировать. Сохраните токен.
  • clientId — идентификатор клиента. Вы можете найти идентификатор в разделе Аналитика → Клиенты. Выберите клиента и сохраните его ID.
  • questionId — идентификатор сообщения. Чтобы получить идентификатор, воспользуйтесь методом GET /chatapi/{token}/client/{clientId}/history.

Обновление статуса сообщения​

Метод POST /chatapi/{token}/client/{clientId}/message/{questionId}/status позволяет изменить статус сообщения. В теле запроса укажите новое значение для поля status.

Обновление статусов сообщений​

Метод POST /chatapi/{token}/client/{clientId}/message-statuses позволяет изменить статусы нескольких сообщений. В теле запроса укажите поле statuses — массив JSON-объектов.

Получение количества непрочитанных сообщений​

Метод GET /chatapi/{token}/client/{clientId}/message-not-read-count позволяет узнать, сколько сообщений не прочитал клиент.