Comment on page

Лия API

Инструмент для программного взаимодействия с ботом.
Взаимодействие осуществляется по протоколу HTTPS с использованием POST-запросов. Максимальное время обработки одного запроса — 30 секунд. Обмен данными осуществляется в формате JSON.
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). Пример:{
    "привет": {"proba": 0.99},
​
​
    "как_дела": {"proba": 0.2}
​
​
}
​
​
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 объект не содержит параметров (пустой объект). При нажатии на кнопку в интерфейсе https://liaplatform.atlassian.net/wiki/spaces/docs/pages/709132338 открывается интерфейс для отправки геопозииции, адреса электронной почты или номера телефон.
​
​
Примеры взаимодействия с 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 - [email protected]"
    }
  }
}
​
Ответное сообщение содержит одно исходящее событие, описанное в 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, так и распознанные сущности (в данном примере — адрес электронной почты).

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

Элемент 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.

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

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

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

Элемент 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.

Элемент JSON	Тип	Описание
Для кнопки типа text
text	string	Необязательный параметр.
Текст для отправки от имени пользователя (имитация сообщения пользователя для бота с целью дальнейшей обработки).
Если данный параметр не указан, то его значение соответствует тексту на кнопке.
Для кнопки типа url
url	string	Обязательный параметр.
Ссылка, которая будет открыта при нажатии на кнопку.
Для кнопки типа intent
text	string	Необязательный параметр.
При нажатии на кнопку этот текст добавляется в переписку как отправленное пользователем сообщение, при этом боту отправляется значение параметра intent_id.
Если данный параметр не указан, то его значение соответствует тексту на кнопке.
intent_id	string	Обязательный параметр
При нажатии на кнопку этот текст отправляется боту, при этом в переписку как отправленное пользователем сообщение добавляется значение параметра text.
Для кнопок типа send_location, send_email , send_phone объект не содержит параметров (пустой объект). При нажатии на кнопку в интерфейсе https://liaplatform.atlassian.net/wiki/spaces/docs/pages/709132338 открывается интерфейс для отправки геопозииции, адреса электронной почты или номера телефон.

Edna

Next - Разработчикам

Работа со сниппетами

Last modified 5mo ago

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

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