Chat API
Aimylogic предоставляет Rest API для интеграции в сторонние приложения. Например, для реализации чата в мобильном приложении, на сайте или в игре.
API предоставляет возможность вести диалог как с ботом, так и с оператором.
Подключение канала Chat API
-
Зайдите в настройки каналов вашего бота и выберите Chat API. Откроется окно настроек канала.
-
Заполните поля:
- Название канала — название, которое будет отображаться в списке подключенных каналов бота.
- Токен — секретный ключ для запроса. Вы можете оставить его пустым, и тогда Aimylogic сгенерирует ключ автоматически.
-
Активируйте переключатель Блокировать ввод текста при использовании кнопок, если хотите заблокировать клиенту возможность ввода текстовых сообщений, когда используете кнопки в сценарии.
-
Нажмите Подключить.
Дождитесь всплывающего окна с результатом публикации. Если публикация прошла успешно, чат-бот готов к использованию.
Токен
Получить его можно с помощью кнопки Скопировать токен или в настройках канала в поле Токен.
Скопируйте его и используйте для доступа к API.
Вебхук для асинхронных запросов
При работе с каналом Chat API вы можете использовать асинхронные запросы. Они позволяют получать сообщения бота или события на указанный вебхук.
Асинхронность позволяет обрабатывать несколько запросов одновременно: вы можете отправлять новые запросы, не ожидая, пока сервер закончит обрабатывать предыдущие. Например, с асинхронными запросами вы можете отправлять рассылки без задержек и получать асинхронные события без дополнительных запросов.
Чтобы указать вебхук:
- Нажмите в строке канала Chat API.
- Введите URL в поле URL вебхука.
Методы API
Отправка запросов клиента в чат
Синхронная отправка
Предоставляются следующие методы для синхронной отправки запроса клиента:
-
Метод возвращает подробную информацию о запросе, в том числе
cid.Опциональное поле
cid— идентификатор соединения. Это произвольная строка, определяющая текущее соединение с чат-приложением. Она может быть далее использована при получении событий в чате, чтобы фильтровать только события во время данного соединения. -
Упрощенный метод, который возвращает несколько параметров запроса:
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 предназначен для получения асинхронных событий от сервера, например:
- Ответ от оператора.
- Изменение состояния виджета на другой странице браузера.
- Запрос клиента, отправленный на другой странице.
- Ответ бота на запрос с другой страницы.
Максимальное количество событий в ответе на запрос — 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 позволяет узнать, сколько сообщений не прочитал клиент.