Messaging API

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

Введение

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

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

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

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

Система 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: <количество байт в теле запроса>

  1. sendText
  2. sendFile
  3. selectDestination
  4. getDestinations

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 Переданные данные не валидны