Лия 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.

Тип

Описание

string

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

float

Вещественное число

Any

Любые данные в формате JSON.

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

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

Элемент JSON Тип Описание

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

user_id

string

Обязательный параметр. Идентификатор пользователя, с которым происходит взаимодействие. Разрешенные символы для user_id — английские буквы, цифры и дефис. В остальных случаях вы будете получать ошибки.

event

JSON-объект

Обязательный параметр. Входящее событие, базовый элемент взаимодействия между пользователем и платформой. Описание объекта приведено ниже

facts

JSON-объект

Необязательный параметр. Факты о пользователе, которые могут быть использованы при выполнении сценариев. JSON-объект с ключами типа string и значениями типа Any.

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

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

Элемент JSON Тип Описание

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

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 Тип Описание

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

Для входящего сообщения типа 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 Тип Описание

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

lat

float

Обязательный параметр. Широта.

lng

float

Обязательный параметр. Долгота.

1.1.2. Объект intents

Элемент JSON Тип Описание

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

intent

JSON-объект

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

1.1.3. Объект entities

Элемент JSON Тип Описание

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

entities

JSON-объект

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

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

Элемент JSON Тип Описание

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

user_id

string

Обязательный параметр. Идентификатор пользователя, с которым происходит взаимодействие.

events

JSON-массив

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

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

Элемент JSON Тип Описание

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

type

string

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

params

JSON-объект

Обязательный параметр. Параметры исходящего события, их тип и количество зависит от типа события. Описание объекта приведено ниже, п. 2.1.

2.1. Объект params

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

Элемент JSON Тип Описание

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

Для исходящего сообщения типа 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-объект

Для исходящего сообщения типа buttons:

text

string

Необязательный параметр. Текст, предшествующий группе кнопок.

buttons

JSON-объект

Обязательный параметр. Кнопки для быстрого ответа пользователем Описание объекта приведено ниже, п. 2.1.1.

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

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

Элемент JSON Тип Описание

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

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 Тип Описание

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

Для кнопки типа 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 - admin@lia.chat"
    }
  }
}

Ответное сообщение содержит одно исходящее событие, описанное в 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, так и распознанные сущности (в данном примере — адрес электронной почты).

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

Last updated 3 months ago