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

Chat API

Chat API позволяет интегрировать чат с Agent Platform в любые приложения, например сайты и игры.

Подключение канала​

Добавить новый канал в проекте можно несколькими способами:

  • В проекте перейдите в раздел Интеграции, выберите Подключить → Канал → Chat API.
  • На холсте нажмите триггер Сообщение и выберите Подключить канал → Chat API.

Укажите параметры:

  1. Задайте название. Оно будет отображаться в списке интеграций.
  2. Укажите URL обратного вызова, если будете его использовать.
  3. Включите Автоматический деплой, чтобы изменения автоматически публиковались в канале при нажатии кнопки Опубликовать на холсте. В противном случае их нужно публиковать вручную кнопкой Опубликовать в триггере Сообщение.
  4. Нажмите Добавить.

Токен для доступа к Chat API​

После создания канала получить токен и адрес для запросов можно двумя способами:

  • В разделе Интеграции нажмите → Получить вебхук у канала Chat API.
  • На холсте нажмите триггер Сообщение, затем Получить вебхук.

Токен — это часть адреса после https://bot.jaicp.com/chatapi/. Пример токена: ZaBcdEfG:123tf0bc456708ea48a89ee1b537211141dd0f41b.

Методы API​

подсказка

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

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

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

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

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

  • POST /chatapi/{token}

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

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

  • GET /chatapi/{token}

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

примечание

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

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

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

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

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

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

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

  • Изменение состояния другого экземпляра чат-приложения.
  • Запрос клиента, отправленный в другом экземпляре.
  • Ответ процесса на запрос из другого экземпляра.
примечание

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

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

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

Метод 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 — идентификатор клиента. Для получения используйте функцию Context.getClientInfo().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 позволяет узнать, сколько сообщений не прочитал клиент.

URL обратного вызова​

Чтобы указать URL для обратного вызова:

  1. Для канала в разделе Интеграции или в триггере Сообщение нажмите → Редактировать.
  2. Введите адрес в поле URL обратного вызова. Нажмите Сохранить.

Agent Platform отправляет событие на URL обратного вызова в следующих случаях:

  • Подготовлен ответ на асинхронный запрос.
  • Вы провели рассылку.
примечание

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

На URL обратного вызова придет массив 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
}