Лия API

Инструмент для программного взаимодействия с ботом. Взаимодействие осуществляется по протоколу HTTPS с использованием POST-запросов. Обмен данными осуществляется в формате JSON.

warning

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

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

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

Доступ к API

warning

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

к сведению

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

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

Взаимодействие построено на основе двух классов событий:

Входящие события инициированы действиями пользователя — события старта диалога, текстовые события, медиа-события и системные события.
Исходящие события возникают со стороны платформы как ответная реакция на входящие события.

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

к сведению

При необходимости передачи сообщения с большим количеством символов рекомендуем разделить его на несколько сообщений.

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

Элемент JSON	Тип	Обязательный	Описание
`user_id`	string	Да	Идентификатор пользователя, с которым происходит взаимодействие. Разрешённые символы — английские буквы, цифры и дефис. В остальных случаях вы будете получать ошибки.
`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`.
`params`	JSON-объект	Да	Параметры входящего события, их тип и количество зависят от типа события. Описание см. ниже, п. 1.1.

Возможные значения type:

text — текстовое сообщение;
image — изображение;
audio — аудиозапись;
video — видеозапись;
file — файл;
sticker — стикер;
location — геопозиция;
start — сигнал старта диалога;
intent — намерение;
raw — намерения и сущности, присылаются вместо текста, чтобы пропустить шаг NLU.

1.1. Объект params

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

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

Тип входящего сообщения	Элемент JSON	Тип	Обязательный	Описание
text	`text`	string	Да	Текст, введённый пользователем.
audio, video, file	`url`	string	Да	Ссылка на файл.
sticker	`sticker_id`	string	Да	Идентификатор стикера.
location	`location`	JSON-объект	Да	Широта и долгота. См. п. 1.1.1.
location	`name`	string	Нет	Название локации.
location	`formatted_address`	string	Нет	Читаемый адрес локации.
start	—	—	—	Не содержит параметров (пустой объект).
intent	`intent`	string	Да	Название намерения. Присылается вместо текста, чтобы пропустить шаг NLU (должно быть определено заранее в разделе «Намерения»).
raw	`intents`	JSON-объект	Нет	Список названий намерений и числовых значений типа float (от 0.00 до 1.00). См. п. 1.1.2.
raw	`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-массив	Да	Ряд событий, являющихся ответной реакцией платформы на входящее событие от пользователя. Массив объектов типа `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	Да	Текст сообщения.
text	`tts`	string	Нет	Текст, который произносится голосовым ассистентом одновременно с отображением текста сообщения пользователю. По умолчанию значение `tts` совпадает со значением `text`.
text	`quick_replies`	JSON-объект	Нет	Подсказки в виде кнопок для быстрого ответа пользователем.
image, audio, video, file	`url`	string	Да	Ссылка на файл.
image, audio, video, file	`caption`	string	Нет	Подпись к файлу.
image, audio, video, file	`quick_replies`	JSON-объект	Нет	Подсказки в виде кнопок. См. п. 2.1.1.
location	`lat`	float	Да	Широта.
location	`lng`	float	Да	Долгота.
location	`name`	string	Нет	Название локации.
location	`quick_replies`	JSON-объект	Нет	Подсказки в виде кнопок. См. п. 2.1.1.
buttons	`text`	string	Нет	Текст, предшествующий группе кнопок.
buttons	`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	`intent_id`	string	Да	При нажатии на кнопку этот текст отправляется боту, при этом в переписку как отправленное пользователем сообщение добавляется значение параметра `text`.

warning

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

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

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

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

Запрос 1

POST /api/v1/handling/event
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
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
POST /api/v1/handling/event?key=12345 HTTP/1.1
Content-Type: application/json

{
  "user_id": "user-128",
  "event": {
    "type": "text",
    "params": {
      "text": "мой email - admin@lia.chat"
    }
  }
}

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

Ответ 2

HTTP/1.1 200 OK
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, так и распознанные сущности (в данном примере — адрес электронной почты).

Примеры curl-запросов

Запрос 1 (curl)

curl example 1
curl -X POST 'https://app.lia.chat/api/v1/handling/event?key=12345' \
-H 'Content-Type: application/json' \
-d '{
  "user_id": "user-128",
  "event": {
    "type": "text",
    "params": {
      "text": "Привет! Запиши меня на демо"
    }
  },
  "facts": {
    "first_name": "Иван",
    "last_name": "Петров"
  }
}'

Запрос 2 (curl)

curl example 2
curl -X POST 'https://app.lia.chat/api/v1/handling/event?key=12345' \
-H 'Content-Type: application/json' \
-d '{
  "user_id": "user-128",
  "event": {
    "type": "text",
    "params": {
      "text": "мой email - admin@lia.chat"
    }
  }
}'

Доступ к API​

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

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

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

1.1. Объект params​

1.1.1. Объект location​

1.1.2. Объект intents​

1.1.3. Объект entities​

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

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

2.1. Объект params​

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

2.1.1.1. Объект params​

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

Запрос 1​

Ответ 1​

Запрос 2​

Ответ 2​

Примеры curl-запросов​

Запрос 1 (curl)​

Запрос 2 (curl)​

Доступ к API

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

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

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

1.1. Объект params

1.1.1. Объект location

1.1.2. Объект intents

1.1.3. Объект entities

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

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

2.1. Объект params

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

2.1.1.1. Объект params

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

Запрос 1

Ответ 1

Запрос 2

Ответ 2

Примеры curl-запросов

Запрос 1 (curl)

Запрос 2 (curl)