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

Chat API

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

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

подсказка

Методы API​

Отправка сообщений клиента​

Запросы, которые клиент отправляет в чат, ваше приложение может передавать на сервер JAICP с помощью синхронных или асинхронных вызовов.

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

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

  • POST /chatapi/{token}

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

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

  • GET /chatapi/{token}

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

примечание

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

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

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

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

Ответ бота можно получить двумя способами:

  • Чат-приложение может запрашивать асинхронные события с сервера JAICP (long polling).
  • Дополнительно, если в настройках канала Chat API задан адрес вебхука, JAICP отправляет ответ на него.

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

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

state: Example
    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.
  • 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 позволяет узнать, сколько сообщений не прочитал клиент.

Вебхук для уведомлений​

Чтобы указать вебхук:

  1. Нажмите  в строке канала Chat API, затем Редактировать.
  2. Введите URL в поле Адрес вебхука.

JAICP отправляет событие на вебхук в следующих случаях:

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

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

На вебхук придет массив 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
}