Messaging API

Версия 1.2. Предумотрена для использования только клиентами платформы Омни 1.1

Введение

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

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

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

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

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

Используемый транспорт: HTTPS с TLS шифрованием (http не поддерживается). Протокол сериализации данных: JSON Доменное имя сервиса: https://messaging.livetex.ru/1.2/ (пока доступна только версия 1.2, но планируется, что для использования будут доступны и другие версии)

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

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

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

Пользователь выбирает направление для маршрутизации обращения (группу операторов)

Touchpoint Gateway оповещает систему LiveTex о выборе направления посетителя (SelectDestination). Все отправленные до выбора направления сообщения сохраняются и будут отправлены после выбора направления.

Обратите внимание: мы не рекомендуем вызывать метод 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>

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

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

Методы Messaging API

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

  1. sendText
  2. sendFile
  3. selectDestination
  4. getDestinations
  5. getHistory
  6. getCurrentDestination

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