Chat API

Aimylogic предоставляет Rest API для интеграции в сторонние приложения. Например, для реализации чата в мобильном приложении, на сайте или в игре.

подсказка

Rest API — это распространенный способ передачи данных на сторонний сервис при помощи HTTP-запросов.

API предоставляет возможность вести диалог как с ботом, так и с оператором.

Подключение канала Chat API

1. Зайдите в настройки каналов вашего бота и выберите Chat API. Откроется окно настроек канала.

   

2. Заполните поля:

   • Название канала — название, которое будет отображаться в списке подключенных каналов бота.
   • Токен — секретный ключ для запроса. Вы можете оставить его пустым, и тогда Aimylogic сгенерирует ключ автоматически.

3. Активируйте переключатель Блокировать ввод текста при использовании кнопок, если хотите заблокировать клиенту возможность ввода текстовых сообщений, когда используете кнопки в сценарии.

4. Нажмите Подключить.

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

Токен

подсказка

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

Получить его можно с помощью кнопки Скопировать токен или в настройках канала в поле Токен.

Скопируйте его и используйте для доступа к API.

Вебхук для асинхронных запросов

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

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

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

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

Методы API

подсказка

Подробнее о методах, параметрах запроса, форматах ответов и возвращаемых ошибках см. в спецификации Chat 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
}

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

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

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

предупреждение

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

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

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

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

предупреждение

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

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

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

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

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

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

• GET /chatapi/{token}/client/{clientId}/state
• POST /chatapi/{token}/client/{clientId}/state

подсказка

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