Messaging API

Текущая версия - 1.0

Введение

API, которое мы с вами рассмотрим далее, служит для обмена сообщениями и файлами с сотрудниками, работающими в приложении Livetex. Ваш сервер может отправлять сотруднику в приложение оператора данные из любого источника и направлять в ответ данные полученные от сотрудника, то есть методы позволяют: Отправить сообщение или ссылку на файл сотруднику; Выбрать, какой именно группе сотрудников будут отправляться сообщения; Передать сотруднику дополнительную информацию о пользователе; Подписаться на уведомления (webhook), посредством которых Messaging API информирует о сообщениях для пользователя, о доставке сообщений пользователя, о необходимости выбрать направление для сообщений, о закрытии обращения сотрудником.

Если представить реализацию в виде диаграммы последовательности, то самая простая интеграция будет выглядеть следующим образом:

Базовые понятия

Собеседник (User/Пользователь) - обращается в чат для получения консультации или поддержки. Собеседник указывается в запросах посредством user_id. Идентификатор контролируется на стороне разработчика, который использует Messaging API. LiveTex не устанавливает идентификаторы пользователей автоматически. По одинаковым идентификаторам LiveTex группирует обращения пользователя. То есть, если в разные моменты времени состоялось несколько обращений от пользователя, для которого в эти разные моменты времени был установлен один и тот же user_id, то сотрудник в приложении, при получении очередного обращения от того же user_id, увидит все предыдущие обращения.
Сотрудник (Employee) - сотрудник организации, обрабатывающий входящие обращения собеседника в приложении LiveTex.
Бот (Bot) - автоматизированная система обработки обращений собеседника.
Направление маршрутизации (Destination) - под направлением, в котором отправляются полученные от собеседника сообщения, подразумеваются группы сотрудников созданные в рамках точки контакта, ключ для которой используется для работы с API. У каждой точки контакта обязательно есть минимум одна группа сотрудников.
Уведомления (Webhook-и) - посылаемые на указанный разработчиком адрес сообщения, которые содержат информацию о новых сообщениях и событиях.

Взаимодействующие компоненты

LiveTex - система омниканального обслуживания.
Touchpoint Gateway - внешняя точка контакта пользователей с бизнесом. Например, бот в Telegram, Facebook или группа в VK, чат на сайте.

Система LiveTex получает от Touchpoint Gateway текстовые и другие медиа-сообщения, отправленные пользователем. Система LiveTex способна отправлять пользователю текстовые и другие медиа-сообщения. Система LiveTex может запросить у пользователя дополнительную информацию для маршрутизации обращения. Все сообщения от операторов и собеседников сохраняются в истории с системе Livetex для предоставления оператору максимально полного контекста обращения.

Используемый транспорт: HTTPS с TLS шифрованием (http не поддерживается).

Протокол сериализации данных: JSON

Доменное имя сервиса: https://messaging.livetex.ru/1.0/ (пока доступна только версия 1.0, но планируется, что для использования будут доступны и другие версии)

Сценарии взаимодействия

Пользователь обращается к сотруднику

Touchpoint Gateway оповещает систему LiveTex о новом сообщении от собеседника вызовом методов sendText либо sendFile. Если до вызова метода отправки сообщения или файла не было явно выбрано направление или предыдущее обращение от пользователя было уже закрыто сотрудником, то LiveTex передаст в сторону Touchpoint Gateway оповещение SelectDestination, предлагая выбрать направление, куда будет отправлено сообщение. Все отправленные до выбора направления сообщения сохраняются и будут отправлены после выбора направления.

Сотрудник отправил ответ пользователю

Система LiveTex оповещает Touchpoint Gateway о новом текстовом сообщении (TextMessage) или файле (FileMessage) от сотрудника. Если url для вебхуков не был задан к моменту ответа оператора, все сообщения от оператора будут сохранены и отправлены после вызова метода setWebhook, но не позднее чем через сутки после отправки сообщения оператором.

Закрытие обращения оператором

Сотрудник в приложении LiveTex Workspace закрывает вкладку с обращением. Система LiveTex посылает событие Closed, оповещая тем самым Touchpoint Gateway о закрытии обращения сотрудником. После этого событие направление маршрутизации считается не выбранным.

Авторизация

Авторизация осуществляется посредством передачи ключа авторизации в параметре каждого запроса:

curl -X POST https://messaging.livetex.ru/<version>/<method>?key=<authentication_key>

То есть отдельно перед выполнением всех запросов проходить авторизацию не требуется. На данный момент вместо \ необходимо указать 1.0 Ключ для авторизации можно получить в личном кабинете https://my.livetex.ru в разделе Настройки - Точки контакта. Нажмите на кнопку “Ключ доступа” напротив вашей точки контакта типа “Messaging API” и вы увидите и сможете скопировать ключ для авторизации, как на этих снимках:

oioo

Сложные типы данных

Методы Messaging API

Все запросы выполняются только по HTTPS.
Все запросы, подразумевающие наличие JSON в теле запроса, должны содержать следующие заголовки: - Content-Type: "application/json" - Content-Length: <количество байт в теле запроса>

Hello World!

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

1.Получаем возможные направления, куда можно отправить сообщение.
Запрос:

curl -X POST https://messaging.livetex.ru/<version>/getDestinations?key=<authentication_key>

Ответ:

{
  "destinations" : [{
    "destination_type" : "Department",
     "destination_id" : "54321",
     "name" : "Группа для Messaging API",
     "has_online" : true
  }],
  "success" : true
}

2.Выбираем подходящее направление и указываем информацию о клиенте.
Запрос:

curl -X POST -d '{
    "user_id": "123-321-123-321",
    "destination_type" : "Department",
    "destination_id" : "54321",
    "name" : "Иванов Василий Петрович",
    "attributes" : {"Номер заказа" : "№98765"}
}' \ https://messaging.livetex.ru/<version>/selectDestination?key=<authentication_key>

Ответ:

{
    "success" : true
}

3.Отправляем сообщение. Запрос:

curl -X POST -d '{
    "user_id": "123-321-123-321",
    "text": "Hello World!"
}' \ https://messaging.livetex.ru/<version>/sendText?key=<authentication_key>

Ответ:

{
    "message_id" : "1f00f857-6afe4-4618-c208-92ad57401abe",
    "timestamp" : 1502783446318,
    "success" : true
}

4.Отправим вдогонку файл. Запрос:

curl -X POST -d '{
        "user_id": "123-321-123-321",
        "url": "https://livetex.ru/wp-content/themes/livetex/ltx/img/Logo_LiveTex.png",
        "file_name": "LiveTex.png",
        "size": 5,
        "comment": "Вот, посмотрите, какой файл я приложил!"
}' \ https://messaging.livetex.ru/<version>/sendFile?key=<authentication_key>

Ответ:

{
    "message_id" : "ed31802b-7c7a-4948-abf5-ff2a34ec7b07",
    "timestamp" : 1502783544207,
    "success" : true
}

Готово, сотрудник получил сообщение и файл. Если на момент выполнения запросов сотрудник не был авторизован в приложении оператора, то он получит сообщение и файл после авторизации.

Чтобы получить ответ от Сотрудника необходимо слушать уведомления от сервера. Уведомления доставляются посредством Webhooks, подключение которых мы рассмотрим далее.

Методы для работы с Webhook

Оповещения посредством Webhook

Статусы HTTP ответов

В случае успешной обработки LiveTex возвращает ответ с кодом 200. Прочие поддерживаемые статусы: 400, 401, 403, 404, 500

Возможные ошибки

Статус	Код	Сообщение	Причина возникновения
400	1	Authentication key is not specified	В запросе не указан ключ авторизации
401	2	Authentication key is not valid	Указанный в запросе authentication_key не зарегистрирован в LiveTex
400	3	Empty body	Пустое тело запроса
400	4	Wrong JSON format	Невалидный формат JSON в запросе
400	5	URL [$url] is not valid: $reason	Для получения Webhook-ов передан невалидный url
404	6	Unsupported HTTP request ${request.method} ${request.path}	Выполнен недопустимый HTTP запрос
500	7	Internal server error	Произошло непредвиденное исключение на стороне LiveTex
403	8	Forbidden method for your account	Метод недоступен для используемой версии продуктов
400	9	Invalid data: $reason	Переданные данные не валидны