Лия 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 и платформой построено на основе событий. Различают два класса событий:

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

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

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

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

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

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

1.1. Объект params

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

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

1.1.1. Объект location

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

1.1.2. Объект intents

1.1.3. Объект entities

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

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

2.1. Объект params

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

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

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

2.1.1.1. Объект params

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

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

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

PreviousEdnaNextМинимальные требования для разработки динамического сценария

Last updated