Лия API

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

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

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

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

Доступ к API

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

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

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

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

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

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

Тип
Описание

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

Текст, введенный пользователем.

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

ПредыдущаяAPI-запросы через сниппетСледующаяИнтеграции

Последнее обновление