- Введение
- Установка
- Базовый сценарий взаимодействия
- Авторизация и открытие WebSocket
- Взаимодействие с сервисом
- События и команды получаемые от сервиса
- Событие state об изменении состояния диалога
- Событие update об изменении сообщений в диалоге
- Событие attributesRequest для запроса атрибутов обращения
- Событие departmentRequest для запроса выбора группы
- Событие employeeTyping для оповещения о наборе текста оператором
- Ответ на выполнения клиентских команд
- Каталог ошибок выполнения команд клиента
- Каталог ошибок работы клиента с сервисом
- События и команды отправляемые клиентом
- События и команды получаемые от сервиса
- Push-уведомления
Введение
Visitor API позволяет реализовать обмен сообщениями из любого источника, например в мобильном приложении.
Документация находится в процессе разработки и ещё будет дополняться. Если у вас появился вопрос, который не раскрыт в данной документации, то вы можете обратиться в службу поддержки, мы постараемся ответить на ваши вопросы.
Установка
Для работы с SDK 3.0 вам потребуется следующее:
- Пройдите регистрацию, как описано тут;
- После регистрации и активации пробного доступа пройдите в личном кабинете в раздел Настройки - Точки контакта. Нажмите на кнопку “Добавить” в верхней правой части и в появившемся модальном окне выберите из выпадающего списка значение “Мобильное приложение”. Далее укажите название для точки контакта и нажмите кнопку “Добавить”.
- После добавления новая точка контакта появится в списке. Напротив неё вы сможете увидеть идентификатор, как на этом снимке:
Для получения ключа доступа в Visitor API нажмите Ключ доступа - Скопировать
Данный ключ доступа используется при инициализации SDK 3.0 и авторизации в Visitor API. - Перейдите в личном кабинете в раздел Настройки - Маршрутизация и добавьте к созданной точке контакта тех сотрудников, которые должны принимать обращения из приложения. Подробнее в этой статье.
Полученные данные потребуются для работы приложения. Для инициализации авторизации Visitor API в запросе потребуется указать ключ доступа (token) точки контакта для параметра touchPoint.
https://visitor-api.livetex.ru/v1/auth?touchPoint=token&deviceToken=device&deviceType=type
Базовый сценарий взаимодействия
На схеме обозначен базовый сценарий взаимодействия посетителя с оператором посредством Visitor API *
* Последовательность отправки событий в ответ на команды от Visitor API должна строго соблюдаться.
Авторизация и открытие WebSocket
Авторизация пользователя
Для авторизации требуется выполнить HTTP запрос к https://visitor-api.livetex.ru/ с параметрами (серым цветом выделены необязательные параметры):
| Имя | Тип | Описание |
| touchPoint | string | Идентификатор определяющий приложение как точку контакта. |
| visitorToken | string | Идентификатор пользователя, который выдаётся бекэндом LiveTex. Если не задан, будет создан новый. |
| customVisitorToken | string | Идентификатор клиента во внешней системе. Например, в CRM заказчика. |
| deviceToken | string | Идентификатор устройства выдаваемый FCM или APNS |
| deviceType | string | Возможные значения: ios, android |
Может быть два варианта авторизации. Использоваться в один момент времени должен какой-либо один из перечисленных, в зависимости от кейса или состояния пользователя:
1. Если вы используете ваши внутренние идентификаторы пользователей, то при авторизации передавайте только customVisitorToken, без visitorToken:
https://visitor-api.livetex.ru/v1/auth?touchPoint=token&customVisitorToken=CustomVisitorToken&deviceToken=device&deviceType=type
2. Если вы не используете ваши внутренние идентификаторы, а только идентификаторы, которые выдаёт LiveTex, то авторизация нового пользователя, когда неизвестен его идентификатор, происходит без указания visitorToken или customVisitorToken. В этом случае система сгенирирует и вернёт новый visitorToken.
Пример запроса авторизации нового пользователя идентификатор которого неизвестен:
https://visitor-api.livetex.ru/v1/auth?touchPoint=token&deviceToken=device&deviceType=type
В результате возвращается объект:
{
"visitorToken": "token",
"endpoints": {
"ws": "wss://visitor-api.livetex.ru/v1/ws/visitorToken"
"upload": "https://visitor-api.livetex.ru/v1/upload"
}
}
Поле visitorToken будет всегда содержать идентификатор сгенерированный сервером LiveTex, но если вы передаёте идентификатор в customVisitorToken, то сервер вернёт всегда одно и то же уникальное значение, которое будет ему соответствовать.
В параметре upload будет возвращен эндпоинт сервиса, на который следует загружать файлы
Полученный visitorToken можно сохранить, чтобы указать при последующей авторизации данного пользователя.
Пример запроса:
https://visitor-api.livetex.ru/v1/auth?touchPoint=token&visitorToken=VisitorToken&deviceToken=device&deviceType=type
Открытие WebSocket
Для установки соединения с сервером по WebSocket необходимо указать адрес и идентификатор посетителя, выданный при авторизации:
wss://visitor-api-02-i2.livetex.ru:443/v1/ws/{visitorToken}
Обратите внимание, что в ответе после авторизации для ws приходят разные адреса.
Если вы после авторизации получили для ws один адрес, но в итоге установили соединение с другим адресом, то часть сообщений поступать не будет.
Взаимодействие с сервисом
События и команды получаемые от сервиса
Событие state об изменении состояния диалога
При открытии соединения, изменении статуса обращения или назначении оператора клиент получает структуру state, которая отражает текущее состояние диалога. Структура имеет следующие параметры (серым отмечены необязательные):
| Имя | Описание |
| type | Указание типа события |
| status |
Статус обращения. Возможные значения: "unassigned" | "inQueue" | "assigned" | "aiBot" где unassigned — обращение не назначено ни в одну из очередей; |
| employeeStatus |
Статус оператора, на которого назначено обращение. Возможные значения: "online" | "offline" |
| employee |
Структура с информацией об операторе, на которого назначено обращение, где name — никнейм; Назначенному оператору можно поставить оценку. Изначально, при назначении оператора, поле rating не задано. Если это поле не задано, то оператору поставить оценку. После установки оценки поле rating приобретет значение, равное оценке указанной с помощью команды rating. Если обращение будет передано другому оператору, то поле rating вновь будет не определено. |
| showInput | Признак необходимости отображать поле для ввода текста. По умолчанию true - поле ввода активно. |
Пример:
{
"type": "state",
"status": "assigned",
"employeeStatus": "online",
"employee": {
"name": "Ivan",
"position": "Управляющий",
"avatarUrl": "https://static-service.livetex.ru/ad12a3sd3asd.png",
"rating": "1"
},
"showInput": true
}
Событие update об изменении сообщений в диалоге
При любом добавлении/изменении сообщений в обращении клиент получает событие update, в котором в поле messages содержатся новые сообщения, либо изменившиеся старые.
Событие update также всегда приходит при открытии websocket канала и, в этом случае, содержит последние 10 сообщений, написанных клиентом или оператором ранее.
Описание параметров:
| Имя | Описание |
| correlationId | Идентификатор связки запроса и ответа |
| type | Указание типа события |
| createdAt | Время обновления, в соответствии с которым поступило уведомление |
| messages | Объект содержащий новые или изменённые сообщения |
Пример:
{
"correlationId": "3bba05bc-768d-4449-8365-44c72db46742",
"type": "update",
"createdAt": "2016-09-28T13:30:41.000Z",
"messages": [
{
"type": "text",
"id": "24853bad-3b30-4f58-987e-39911a38ef3a",
"correlationId": "3bba05bc-768d-4449-8365-44c72db4695d",
"createdAt": "2016-09-28T13:30:41.000Z",
"creator": {
"type": "employee",
"employee": {
"name": "Ivan",
"position": "Управляющий",
"avatarUrl": "https://static-service.livetex.ru/ad12a3sd3asd.png"
}
},
"content": "Hello"
}
]
}
Возможное содержание объекта messages:
- Текстовое сообщение
{
"type": "text",
"id": "24853bad-3b30-4f58-987e-39911a38ef3a",
"correlationId": "3bba05bc-768d-4449-8365-44c72db4695d",
"createdAt": "2016-09-28T13:30:41.000Z",
"creator": {
"type": "employee",
"employee": {
"name": "Ivan",
"position": "Управляющий",
"avatarUrl": "https://static-service.livetex.ru/ad12a3sd3asd.png"
}
},
"content": "Hello"
}
- Кнопки в текстовом сообщении
Существует два типа кнопок: с простым текстом и кнопка со ссылкой. Кнопка со ссылкой содержит поле url. Каждая кнопка содержит поле payload, значение которого необходимо отправить в сервис с помощью команды buttonPressed.
{
"type": "text",
"id": "24853bad-3b30-4f58-987e-39911a38ef3a",
"correlationId": "3bba05bc-768d-4449-8365-44c72db4695d",
"createdAt": "2016-09-28T13:30:41.000Z",
"creator": {
"type": "bot"
},
"content": "Hello",
"keyboard": {
"buttons": [
{
"label": "Button 1",
"payload": "\u2064Button 1|payload:123"
},
{
"label": "Link button 2",
"url": "https://link.to/path",
"payload": "\u2064Link button 2|url:https://link.to/path|payload:123"
}
],
"pressed": true
},
"attributes": [ // optional
{
"name": "Name",
"value": "Value"
}
]
}
- Файловое сообщение
{
"type": "file",
"id": "63f7156d-fee0-4562-8ed5-a5195f40a9ac",
"correlationId": "3ba5087b-9458-4dfb-aa1c-a66668c9902a",
"createdAt": "2016-09-28T13:30:41.000Z",
"creator": {
"type": "visitor"
},
"name": "document.docx",
"url": "https://file-service.livetex.ru/ad12a3sd3asd.docx"
}
- Системное сообщение
Это текстовое сообщение с создателем типа system. Системные сообщения могут отправляться клиенту в случае попадания в очередь, назначения на оператора, закрытия им обращения, оценке консультации посетителем и при отправке системой удерживающих сообщений.
{
"type": "text",
"id": "63f7156d-fee0-4562-8ed5-a5195f40a9ac",
"createdAt": "2016-09-28T13:30:41.000Z",
"creator": {
"type": "system"
},
"content": "Обращение назначено на сотрудника Иван"
}
Событие attributesRequest для запроса атрибутов обращения
При инициации взаимодействия со стороны клиента, то есть при начале нового обращения посредством отправки текстового сообщения, клиент получает запрос на установку атрибутов.
{
"type": "attributesRequest"
}
В ответ нужно отправить команду отправки атрибутов обращения. Если атрибуты не будут своевременно отправлены, оператор не получит имя посетителя и переданные по нему данные.
Событие departmentRequest для запроса выбора группы
При начале обращения сервис запрашивает, в какую группу операторов требуется направить обращение. В событии содержится список возможных для установки групп.
Если к точке контакта привязана только одна группа, запрос выбора группы отправлен не будет - обращение будет направлено в привязанную группу автоматически.
{
"type": "departmentRequest",
"departments": [
{
"id": "20012",
"name": "Tech Support",
"order": 1
},
{
"id": "20013",
"name": "Sales",
"order": 2
}
]
}
Событие employeeTyping для оповещения о наборе текста оператором
В случае набора текста оператором, раз в ~3 секунды будет приходить событие employeeTyping. Если событие не поступает более 3 секунд, это указывает на то, что оператор перестал набирать ответное сообщение.
{
"type": "employeeTyping",
"createdAt": "2016-09-28T13:30:41.000Z"
}
Ответ на выполнения клиентских команд
После получения и обработки команды клиента сервис возвращает ему result с тем же correlationId. Параметр correlationId задаётся разработчиком и служит связкой между запросом клиента и ответом от сервиса. Если команда клиента подразумевает отправку сообщения, то result будет содержать поле sentMessage с датой создания сообщения и его id. Если выполнение команды клиента приводит к ошибке, то поле errors содержит список строковых констант,
соответствующих определенным видам ошибок.
Пример:
{
"type": "result",
"correlationId": "c36cc714-42ac-11ea-b77f-2e728ce88125",
"sentMessage": {
"createdAt": "2016-09-28T13:30:41.000Z",
"id": "c35abf7c-ba58-4989-abb4-22ca3d269ec9"
},
"errors": [
"fileNoUrl",
"fileNoName"
]
}
Каталог ошибок выполнения команд клиента
Список кодов ошибок. Коды - текстовые константы, префиксом является название команды.
| Код ошибки | Причина |
| systemUnavailable | Сервис приёма сообщений недоступен |
| fileNoName | В команде file нет или пустое поле name |
| fileNoUrl | В команде file нет или пустое поле url |
| textContentIsEmpty | В команде text нет или пустое поле content; |
| attributesWrongFormat | В команде attributes атрибуты переданы не в виде Map<string, string> |
| departmentNoId | В команде department пустое поле id |
| departmentInvalidId | В команде department передан невалидный или несуществующий id группы |
| historyFromMessageIdNotDefined | В команде getHistory не определен messageId от которого будет возвращена история |
| buttonPayloadIsEmpty | В команде ButtonPressed не определен payload |
| ratingValueIsEmpty | В команде Rating не задан параметр value |
Каталог ошибок работы клиента с сервисом
В данном случае имеются в виду ошибки, которые мы не можем привязать к конкретному запросу. Таким образом мы сообщаем, что запрос в целом составлен неправильно. Эти ошибки скорее не влияют на поведение приложения, а предназначены для разработчика. То есть их можно, как минимум, логировать. В качестве кодов используются строковые константы:
| Код ошибки | Причина |
| requestMissingFieldType | В запросе нет обязательного поля type; |
| requestMissingFieldCorrelationId | В запросе нет обязательного поля correlationId; |
| tooManyRequests | Слишком много запросов, рейт-лимит |
Пример:
{
"type": "error",
"code": "requestMissingFieldType"
}
События и команды отправляемые клиентом
Во всех командах есть поле correlationId, в котором передаётся идентификатор задаваемый разработчиком. Данный идентификатор служит связкой запроса и ответа от сервиса. Идентификатор может быть любым.
Команда отправки сообщения
{
"correlationId": "b0d0e2b6-42ac-11ea-b77f-2e728ce88125",
"type": "text",
"content": "Hello"
}
Команда отправки файла
Перед передачей, файл необходимо загрузить используя адрес полученный при авторизации в параметре endpoints.upload.
Загрузка файла на сервер осуществляется с помощью multipart/form-data (https://tools.ietf.org/html/rfc7578).
Пример curl команды отправки файла:
curl -v -H 'Authorization: Bearer visitorToken -H 'Content-Type: multipart/form-data' -F fileUpload=@"/home/user/picture.png" -X POST 'upload'
Вместо visitorToken необходимо подставить значение этого параметра, полученное при авторизации.
Путь к файлу необходимо передавать в поле формы fileUpload.
Вместо upload необходимо указать значение адреса для загрузок, которое также было получено при авторизации.
В результате успешной отправки придет ответ вида:
{
"name" : "picture.png",
"url" : "https://file-service/e87be187-8bae-4dc2-8547-35ab54965b46/picture.png"
}
Затем необходимо отправить событие используя url полученный в предыдущем ответе:
{
"correlationId": "ba2f92da-42ac-11ea-b77f-2e728ce88125",
"type": "file",
"name": "picture.png",
"url": "https://file-service/e87be187-8bae-4dc2-8547-35ab54965b46/picture.png"
}
Команда выбора группы клиентом
{
"correlationId": "cd8e2ff8-42ac-11ea-b77f-2e728ce88125",
"type": "department",
"id": "123"
}
Команда отправки атрибутов обращения
Данную команду необходимо отправить в ответ на команду от сервера attributesRequest.
В полях можно передать необходимую оператору информацию о посетителе. Переданная информация будет отображаться в Приложении оператора и в Личном кабинете.
Атрибуты можно обновить в любой момент общения, при условии что обращение находится в работе (не закрыто оператором)
В данной команде обязательными являются поля correlationId, type и attributes.
{
"correlationId": "0977e2f2-42ad-11ea-b77f-2e728ce88125",
"type": "attributes",
"name": "Vasiliy",
"phone": "+7-282-123-12-12",
"email": "vasya@gmail.com",
"attributes": {
"VIP-client": "true",
"CRM id": "10023"
}
}
Команда на получение истории
Команда позволяет запросить ранее написанные в диалоге сообщения. Сообщения придут в команде сервиса update в поле messages. Поле messageId должно содержать id сообщения в диалоге, от которого необходимо получить более ранние сообщения. Количество получаемых сообщений регулируется полем offset. Поле offset должно быть больше 0.
{
"correlationId": "0977e2f2-42ad-11ea-b77f-2e728ce88125",
"type": "getHistory",
"messageId": "c36cc714-42ac-11ea-b77f-2e728ce88125",
"offset": 10
}
Команда оценки оператора посетителем
Посетитель может оценить назначенного на него оператора, но только в том случае, если поле rating в структуре employee в событии state не определено. После отправки команды но проставление оценки, клиенту будет передано событие state, где в структуре employee поле rating примет переданное в команде значение. Поле value может иметь значение 1 (положительно) или 0 (отрицательно).
{
"type": "rating",
"correlationId": "63f7156d-fee0-4562-8ed5-a5195f40a9ac",
"value": "1"
}
Событие набора текста клиентом
{
"type": "typing",
"content": "Hel"
}
Событие нажатия на кнопку
Если пользователь нажал на кнопку, то необходимо отправить в сервис параметр payload нажатой кнопки.
{
"correlationId": "0977e2f2-42ad-11ea-b77f-2e728ce88125",
"type": "buttonPressed",
"payload": "\u2064Button 1|payload:123"
}
Push-уведомления
Для отправки уведомлений используются те же механизмы что и для SDK 3.0. С сервера LiveTex может либо поступать на ваш сервер уведомление о необходимости отправить уведомление и отправка осуществляется с вашего сервера, либо вы можете передать в LiveTex сертификаты/ключи для работы с APNS и FCM, тогда мы подключим отправку уведомлений с сервера LiveTex через указанные сервисы. Подробнее в этих статьях:
Комментарии