Лия API

Инструмент для программного взаимодействия с ботом.

Взаимодействие осуществляется по протоколу HTTPS с использованием POST-запросов.

Обмен данными осуществляется в формате JSON.

Максимальное время обработки одного запроса — 30 секунд.

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

https://app.lia.chat/api/v1/handling/event?key=API_KEY

Доступ к API

Чтобы запросы к API проходили, необходимо опубликовать проект.

Для работы с необходимо получить ключ API_KEY. Для этого в разделе “Каналы” необходимо нажать кнопку “Добавить” и в выпадающем списке выбрать пункт “API”. Полученный ключ API_KEY будет отображен в центральной части страницы.

Принципы взаимодействия и типы данных

Взаимодействие между пользователем API и платформой построено на основе событий. Различают два класса событий:

• Входящие события инициированы действиями пользователя, к ним относятся: события старта диалога, текстовые события, медиа события, системные события.

• Исходящие события возникают со стороны платформы как ответная реакция на входящие события.

Тип	Описание
string	Текстовая строка, длина не превышает 1024 символов. Пр необходимости передачи сообщения с большим количеством символов рекомендуем разделить его на несколько сообщений
float	Вещественное число
Any	Любые данные в формате JSON.

1. Входящие события

Параметры входящего события.

Элемент JSON	Тип	Описание
user_id	string	Обязательный параметр. Идентификатор пользователя, с которым происходит взаимодействие. Разрешенные символы для user_id — английские буквы, цифры и дефис. В остальных случаях вы будете получать ошибки.
event	JSON-объект	Обязательный параметр. Входящее событие, базовый элемент взаимодействия между пользователем и платформой. Описание объекта приведено ниже
facts	JSON-объект	Необязательный параметр. Факты о пользователе, которые могут быть использованы при выполнении сценариев. JSON-объект с ключами типа string и значениями типа Any.

Объект event (для входящих событий)

Объект event — базовый элемент взаимодействия, в котором передаются тип события и необходимые для его обработки параметры. Объект event для входящих событий отличается от объекта event для исходящих событий возможными значениями параметров type и params.

Элемент JSON	Тип	Описание
type	string	Обязательный параметр. Тип события, от которого зависит набор параметров входящего сообщения. Возможные значения: • text — текстовое сообщение; • image — изображение; • audio — аудиозапись; • video — видеозапись; • file — файл; • sticker — стикер; • location — геопозиция; • start — сигнал старта диалога; • intent — намерение; • raw — намерения и сущности, присылаются вместо текста, чтобы пропустить шаг NLU.
params	JSON-объект	Обязательный параметр. Параметры входящего события, их тип и количество зависит от типа события. Описание объекта приведено ниже, п. 1.1.

1.1. Объект params

В зависимости от значения параметра type (типа входящего сообщения) объект params содержит разные параметры.

Данный объект используется как одно из значений поля params в объекте event для входящих событий. Не путать с одноименными объектами использующихся в других местах.

Элемент JSON	Тип	Описание
Для входящего сообщения типа text:
text	string	Обязательный параметр. Текст, введенный пользователем.
Для входящего сообщения типа image, audio, video, file:
url	string	Обязательный параметр. Ссылка на файл.
Для входящего сообщения типа sticker:
sticker_id	string	Обязательный параметр. Идентификатор стикера.
Для входящего сообщения типа location:
location	JSON-объект	Обязательный параметр. Ширина и долгота. Описание объекта приведено ниже, п. 1.1.1.
name	string	Необязательный параметр. Название локации.
formatted_address	string	Необязательный параметр. Читаемый адрес локации.
Для входящего сообщения типа start объект не содержит параметров (пустой объект).
Для входящего сообщения типа intent:
intent	string	Обязательный параметр. Название намерения. Присылается вместо текста, чтобы пропустить шаг NLU (должно быть определено заранее в разделе “Намерения”).
Для входящего сообщения типа raw:
intents	string	Необязательный параметр. Список названий намерений (должны быть определены заранее в разделе “Намерения”).
	JSON-объект	Необязательный параметр. Список названий намерений (должны быть определены заранее в разделе “Намерения”) и числовых значений типа float (в диапазоне от 0.00 до 1.00). Описание объекта приведено ниже, п. 1.1.2.
entities	JSON-объект	Необязательный параметр. Список названий сущностей (должны быть определены заранее в разделе “Сущности”) и значений типа Any. Описание объекта приведено ниже, п. 1.1.3.

1.1.1. Объект location

Объект location для входящих событий отличается от объекта location исходящих событий.

Элемент JSON	Тип	Описание
lat	float	Обязательный параметр. Широта.
lng	float	Обязательный параметр. Долгота.

1.1.2. Объект intents

Элемент JSON	Тип	Описание
intent	JSON-объект	JSON-объект с ключами типа string, которые являются названиями намерений (должны быть определены заранее в разделе “Намерения”), и значениями типа JSON-объект, который, в свою очередь, состоит из элемента proba типа float (принимает значения в диапазоне от 0.00 до 1.00).

1.1.3. Объект entities

Элемент JSON	Тип	Описание
entities	JSON-объект	JSON-объект с ключами типа string, которые являются названиями сущностей (должны быть определены заранее в разделе “Сущности”), и значениями типа Any.

2. Исходящие события

Элемент JSON	Тип	Описание
user_id	string	Обязательный параметр. Идентификатор пользователя, с которым происходит взаимодействие.
events	JSON-массив	Обязательный параметр. Ряд событий, являющихся ответной реакцией платформы на входящее событие от пользователя. JSON-массив объектов типа event (для исходящих событий). Описание объекта приведено ниже.

Объект event (для исходящих событий)

Элемент JSON	Тип	Описание
type	string	Обязательный параметр. Тип входящего события, от которого зависит набор параметров входящего сообщения. Возможные значения: • text — текстовое сообщение • image — изображение • audio — аудиозапись • video — видеозапись • file — файл • location — геопозиция • произвольный (из snippet можно отправить произвольное событие) — JSON-объект с ключами типа string и значениями типа Any.
params	JSON-объект	Обязательный параметр. Параметры исходящего события, их тип и количество зависит от типа события. Описание объекта приведено ниже, п. 2.1.

2.1. Объект params

Данный объект используется как одно из значений поля params в объекте event для исходящих событий. Не путать с одноименными объектами использующихся в других местах.

Элемент JSON	Тип	Описание
Для исходящего сообщения типа text:
text	string	Обязательный параметр. Текст, введенный пользователем.
tts	string	Необязательный параметр. Текст, который произносится голосовым ассистентом одновременно с отображением текста сообщения пользователю. По умолчанию значение tts совпадает со значением text.
quick_replies	JSON-объект	Необязательный параметр. Подсказки в виде кнопок для быстрого ответа пользователем.
Для исходящего сообщения типа image, audio, video, file:
url	string	Обязательный параметр. Ссылка на файл.
caption	string	Необязательный параметр. Подпись к файлу.
quick_replies	JSON-объект	Необязательный параметр. Подсказки в виде кнопок для быстрого ответа пользователем. Описание объекта приведено ниже, п. 2.1.1.
Для исходящего сообщения типа location:
lat	float	Обязательный параметр. Широта.
lng	float	Обязательный параметр. Долгота.
name	string	Необязательный параметр. Название локации.
quick_replies	JSON-объект	Необязательный параметр. Подсказки в виде кнопок для быстрого ответа пользователем. Описание объекта приведено ниже, п. 2.1.1.
Для исходящего сообщения типа buttons:
text	string	Необязательный параметр. Текст, предшествующий группе кнопок.
buttons	JSON-объект	Обязательный параметр. Кнопки для быстрого ответа пользователем Описание объекта приведено ниже, п. 2.1.1.

2.1.1. Объекты quick_replies и buttons

Объекты quick_replies и buttons идентичны, это списки не более чем из 20 JSON-объектов со следующими полями:

Элемент JSON	Тип	Описание
type	string	Обязательный параметр. Тип кнопки. Возможные значения: • text • url • intent • send_location • send_email • send_phone
title	string	Обязательный параметр. Текст на кнопке.
params	JSON-объект	Обязательный параметр. Параметры кнопки. Описание объекта приведено ниже, п. 2.1.1.1.

2.1.1.1. Объект params

В зависимости от значения параметра type (типа кнопки) объект params содержит разные параметры.

Данный объект используется как одно из значений поля params в объекте buttons (п. 2.1.1) . Не путать с одноименными объектами использующихся в других местах.

Элемент JSON	Тип	Описание
Для кнопки типа text:
text	string	Необязательный параметр. Текст для отправки от имени пользователя (имитация сообщения пользователя для бота с целью дальнейшей обработки). Если данный параметр не указан, то его значение соответствует тексту на кнопке.
Для кнопки типа url:
url	string	Обязательный параметр. Ссылка, которая будет открыта при нажатии на кнопку.
Для кнопки типа intent:
text	string	Необязательный параметр. При нажатии на кнопку этот текст добавляется в переписку как отправленное пользователем сообщение, при этом боту отправляется значение параметра intent_id. Если данный параметр не указан, то его значение соответствует тексту на кнопке.
intent_id	string	Обязательный параметр При нажатии на кнопку этот текст отправляется боту, при этом в переписку как отправленное пользователем сообщение добавляется значение параметра text.

Для кнопок типа send_location, send_email , send_phone объект не содержит параметров (пустой объект). При нажатии на кнопку в интерфейсе канала открывается интерфейс для отправки геопозиции, адреса электронной почты или номера телефона.

Примеры взаимодействия с API

Рассмотрим несколько примеров взаимодействия пользователя с API.

В первом запросе бот получает событие типа text с параметром в виде текстовой строки. Идентификатор пользователя содержит строку “user-128”. Дополнительно передается несколько фактов о пользователе в JSON-объекте facts — имя и фамилия. Использованы ключи "first_name" и "last_name", выбранные пользователем.

Запрос 1

POST /api/v1/handling/event?key=12345 HTTP/1.1
Content-Type: application/json

{
  "user_id": "user-128",
  "event": {
    "type": "text",
    "params": {
      "text": "Привет, Lia! Запиши меня на демо"
    }
  },
  "facts": {
    "first_name": "Иван",
    "last_name": "Петров"
  }
}

Ответное сообщение содержит идентификатор пользователя с тем же значением, а так же два исходящих события, описанных в JSON-массиве events. Оба события текстового типа, в качестве параметра содержат текстовые строки. Одна из строк содержит имя пользователя, переданное ранее в JSON-объекте facts.

Ответ 1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 269

{
  "user_id": "user-128",
  "events": [
    {
      "type": "text",
      "params": {
        "text": "Здравствуйте, Иван!"
      }
    },
    {
      "type": "text",
      "params": {
        "text": "Напишите ваш email"
      }
    }
  ]
}

Во втором запросе бот получает событие типа text с параметром в виде текстовой строки. Значение параметра user_id остается без изменений на протяжении всего взаимодействия с пользователем.

Запрос 2

POST /api/v1/handling/event?key=12345 HTTP/1.1
Content-Type: application/json

{
  "user_id": "user-128",
  "event": {
    "type": "text",
    "params": {
      "text": "мой email - [e-mail]"
    }
  }
}

Ответное сообщение содержит одно исходящее событие, описанное в JSON-массиве events.

Ответ 2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 21

{
  "user_id": "user-128",
  "events": [
    {
      "type": "text",
      "params": {
        "text": "Иван, записала вас, подробности выслала на почту"
      }
    }
  ]
}

При взаимодействии с пользователем через API бот выполняет заранее составленные сценарии, которые позволяют обрабатывать как данные, переданные в JSON-объекте facts, так и распознанные сущности (в данном примере — адрес электронной почты).