Содержание

Введение
Условные обозначения
Начало работы
Методы Bot API
События Bot API Webhooks

Введение

Bot API позволяет реализовать асинхронное взаимодействие с внешними бот-сервисами из каналов коммуникации LiveTex.

Livetex Bot API предлагает бот-сервису ряд методов, позволяющих отправлять и получать различные коммуникационные сообщения, события по обращениям посетителей из всех каналов коммуникации LiveTex. Bot API позволяет получать и задавать параметры обращений, получать текущие статусы и информацию о доступности операторов или групп операторов аккаунта в LiveTex.

С помощью Bot API можно организовать гибкую маршрутизацию обращений посетителей на операторов аккаунта в LiveTex. Bot API дает возможность пользоваться кнопками в мессенджерах, а также их реализацией в виджете на сайте и SDK для мобильных приложений.

Условные обозначения

Документация находится в процессе разработки и будет дополняться.

✔ - Функциональность реализована

Если у вас появился вопрос, который не раскрыт в данной документации, то вы можете обратиться в службу поддержки, мы постараемся ответить на ваши вопросы.

Начало работы

Для начала работы аккаунта в LiveTex с бот-сервисом необходимо включить чат-бот в разделе Каналы - Настройки бота на выбранных точках контакта, и указать Webhook URL.
Webhook URL определяет адрес, на который LiveTex будет отправлять все коммуникационные события, события по изменению данных операторов, состава групп операторов, статусам и доступности операторов и групп операторов.
Для каждого канала можно задать свой Webhook URL

В дополнение вы можете указать Webhook headers, пока что для этого необходимо обратиться к Технической поддержке Livetex или к персональному менеджеру аккаунта в LiveTex.

В результате вы получите токен интеграции, который позволит отправлять запросы.

Все запросы в Bot-API выполняются на адрес:

https://bot-api.livetex.ru

Правила отправки запросов к Bot-API:

1. Запросы в Bot-API необходимо дополнять заголовком Bot-Api-Token с полученным токеном интеграции с ботом.

2. Все переменные в url должны быть URL encoded.

Методы Bot-API

✔ Отправка текстового сообщения и кнопок

POST /v1/channel/$channelId/visitor/$visitorId/text

{

"text": "Message text",

"buttons": [

{

"type": "textButton",

"label": "Button label",

"payload": "smth-data-1",

"cssClassName": "redButtonClass"

},

{

"type": "linkButton",

"url": "http://link.to",

"newtab": true,

"payload": "smth-data-2"

}

],

"notice": "Text if buttons is not applicable",

"showInput": true

}

В поле text передается отправляемое собеседнику простое текстовое сообщение.

В поле buttons можно передать собеседнику список кнопок.

textButton - обычная текстовая кнопка,

linkButton - кнопка со ссылкой, ведущей на внешний ресурс. Кнопка с ссылкой содержит параметр newtab, который определяет поведение при нажатии на кнопку в виджете на сайте - в случае значения true - ссылка откроется в новой вкладке,

Параметр payload имеет тип строка UTF-8 символов. payload позволяет бот-сервису передать внутреннюю техническую информацию и связать переданную кнопку с фактом нажатия на неё. При нажатии на кнопку её payload вернется в событии VisitorButtonPressed.

Параметр notice опциональный, позволяет передать текст, который будет отправлен собеседнику, в случае если канал не поддерживает кнопки, например, WhatsApp.

Опциональное поле showInput позволяет передать информацию о необходимости показать поле ввода в виджетах на сайте и мобильном SDK при получении данного сообщения. Значение showInput по умолчанию false.

✔ Отправка файла

POST /v1/channel/$channelId/visitor/$visitorId/file

{

"file": "http://bot-service.com/path/to/filename.txt",

"text": "This is a file"

}

Параметр text опциональный.

✔ Задание атрибутов обращения

POST /v1/channel/$channelId/visitor/$visitorId/attributes

{

"attributes": [
 {

"name": "Name",

"value": "Value",

"hidden": false

}

],

"visitorName": "Visitor Name"

}

Параметры attributes и visitorName опциональны.

✔ Маршрутизация собеседника

POST /v1/channel/$channelId/visitor/$visitorId/route

{

"groupId": "234345",

"operatorId": "453648"

}

Может быть указан параметр groupId или operatorId для маршрутизации, соответственно, на конкретную группу или оператора. Если указаны оба параметра, то это приведёт к маршрутизации собеседника на оператора в контексте указанной группы. Если ни один параметр не указан, то коммуникационная платформа сама выберет куда перенаправить обращение собеседника.

✔ Маршрутизация собеседника на офлайн заявку

POST /v1/channel/$channelId/visitor/$visitorId/routeToOffline

{

"groupId": "234345",

"operatorId": "453648",

"visitorEmail": "visitor-email@mail.com",

"messageToOperator": "Текстовое сообщение оператору"

}

✔ Получить список всех каналов

GET /v1/channels

Response

[

{

"id": "454636",

"type": ChannelType,

"active": true,

"webhookUrl": "https://bot-api.service.com",

"eventTypes": [WebhookEventType],

"groups": ["46465", "43434"]

}

]

Возвращаются все каналы на аккаунте. Если в канале подключена интеграция с ботом, то поля active, webhookUrl и eventTypes не нулевые.

✔ Получить список групп

GET /v1/groups

Response

[

{

"id": "36467",

"name": "Group 1",

"hidden": false,

"channels": ["567522", "564773"],

"operators": ["34344", "38655"]

}

]

✔ Получить список операторов

GET /v1/operators

Response

[

{

"id": "36467",

"firstname": "Вася",

"lastname": "Петров",

"nickname": "vasya2000",

"groups": ["123342", "32345"]

}

]

✔ Сбросить настройки бота

POST /v1/channel/$channelId/invalidateSettings

{}

Метод позволяет сбросить настройки бота с приветственным сообщением и первоначальным набором кнопок.

События Bot-API Webhooks

Обратите внимание: Если бот начал присылать ошибки в ответ на запросы от LiveTex или перестал отвечать в течение некоторого времени, то клиент будет автоматически переключен на сотрудника вашего аккаунта (обращение будет передано в очередь точки контакта, к которой подключен бот).

✔ Запрос настроек бота

GET $webhookUrl?channelId=348784

Пример ответа, который требуется послать в ответ на запрос настроек.

Виджет продолжит работать в режиме чата с оператором, если ответ не последует.

{

"headText": "Роббот ЛАТТО на связи",

"botName": "Роббот ЛАТТО",

"botAvatar":"https://avatar.com/avatar/robotLatto.png",

"text": "Greeting message",

"picture": "",

"buttons": [

{

"type": "textButton",

"label": "Button label",

"payload": "smth-data-1",

"cssClassName": "redButtonClass"

},

{

"type": "linkButton",

"url": "http://link.to",

"newtab": true,

"payload": "smth-data-2"

}

],

"showInput": true,

"cssClasses": {

"buttons": [

{

"cssClassName": "redButtonClass",

"color": "#fffff",

"background": "#ff0000",

"border": "#ff0000"

}

]

}

}

Запрос настроек бота для виджета на сайте и чата в мобильном SDK. Этот метод вызывает коммуникационная платформа, например, для показа приветственного сообщения бота, в том числе с первоначальным набором кнопок, в момент, когда виджет первый раз показывается собеседнику на сайте, еще до начала какого-либо обращения, до первого сообщения.

✔ Собеседник отправил текстовое сообщение

POST $webhookUrl

{

"type": "VisitorTextSent",

"id": "38beb6d7-48a3-467a-8b48-51fc648f8b08",

"createdAt": UnixTimestamp,

"channelId": "348784",

"channelType": ChannelType,

"visitorId": "4985498573498598",

"text": "Smth te"

}

✔ Собеседник отправил файл

POST $webhookUrl

{

"type": "VisitorFileSent",

"id": "c4adcbd2-dc04-496f-a603-dc4397efe58a",

"createdAt": UnixTimestamp,

"channelId": "348784",

"channelType": ChannelType,

"visitorId": "4985498573498598",

"files": ["http://livetex.ru/file/filename.txt"]

}

✔ Собеседник нажал кнопку

POST $webhookUrl

{

"type": "VisitorButtonPressed",

"id": "027ec00a-4cf1-4aa9-b1c2-d760a4e049bc",

"createdAt": UnixTimestamp,

"channelId": "348784",

"channelType": ChannelType,

"visitorId": "4985498573498598",

"payload": "smth-data-1"

}

✔ Обновление атрибутов обращения

POST $webhookUrl

{

"type": "ConversationAttributesChanged",

"id": "920ac496-1fd1-4354-8da1-892cd5323f3e",

"createdAt": UnixTimestamp,

"channelId": "348784",

"channelType": ChannelType,

"visitorId": "4985498573498598",

"visitorName": "Visitor Name",

"attributes": [

{

"name": "Name",

"value": "Value",

"type": AttributeType

}

]

}

Поля visitorName и attributes опциональны.

✔ Список типов атрибутов обращения

AttributeType = "Visible" | "Hidden"

✔ Событие создания группы

POST $webhookUrl

{

"type": "GroupCreated",

"id": "16daa15d-6317-4807-8ed2-004d6c1ed2a7",

"createdAt": UnixTimestamp,

"group": {

"id": "34532",

"name": "Поддержка",

"hidden": false

}

}

✔ Событие изменения группы

POST $webhookUrl

{

"type": "GroupChanged",

"id": "16daa15d-6317-4807-8ed2-004d6c1ed2a7",

"createdAt": UnixTimestamp,

"group": {

"id": "34532",

"name": "Поддержка",

"hidden": false

}

}

✔ Событие удаления группы

POST $webhookUrl

{

"type": "GroupDeleted",

"id": "e58e9573-fc64-479d-b4e5-19fe2aca8d52",

"createdAt": UnixTimestamp,

"groupId": "456354"

}

✔ Событие создания канала

POST $webhookUrl

{

"type": "ChannelCreated",

"id": "969e05e6-801e-4237-9186-26e18466b7f2",

"createdAt": UnixTimestamp,

"channelId": "456354"

}

✔ Событие изменения канала

POST $webhookUrl

{

"type": "ChannelChanged",

"id": "969e05e6-801e-4237-9186-26e18466b7f2",

"createdAt": UnixTimestamp,

"channelId": "456354"

}

✔ Событие удаления канала

POST $webhookUrl

{

"type": "ChannelDeleted",

"id": "969e05e6-801e-4237-9186-26e18466b7f2",

"createdAt": UnixTimestamp,

"channelId": "456354"

}

✔ Событие создания оператора

POST $webhookUrl

{

"type": "OperatorCreated",

"id": "021fb3e2-f226-4abd-acec-77447286b1b4",

"createdAt": UnixTimestamp,

"operator": {

"id": "78796",

"firstname": "Иван",

"lastname": "Иванов",

"nickname": "vanya_super"

}

}

✔ Событие изменения оператора

POST $webhookUrl

{

"type": "OperatorChanged",

"id": "021fb3e2-f226-4abd-acec-77447286b1b4",

"createdAt": UnixTimestamp,

"operator": {

"id": "78796",

"firstname": "Иван",

"lastname": "Иванов",

"nickname": "vanya_super"

}

}

✔ Событие удаления оператора

POST $webhookUrl

{

"type": "OperatorDeleted",

"id": "d73e0aae-8f55-487e-892e-ef645968d7f2",

"createdAt": UnixTimestamp,

"operatorId": "32456"

}

✔ Событие добавления связи группа-канал

POST $webhookUrl

{

"type": "GroupChannelRelationCreated",

"id": "d73e0aae-8f55-487e-892e-ef645968d7f2",

"createdAt": UnixTimestamp,

"groupId": "325462",

"channelId": "49893",

"allChannelsOfGroup": ["49893", "36272"],

"allGroupsOfChannel": ["325462", "236726"]

}

✔ Событие удаления связи группа-канал

POST $webhookUrl

{

"type": "GroupChannelRelationDeleted",

"id": "d73e0aae-8f55-487e-892e-ef645968d7f2",

"createdAt": UnixTimestamp,

"groupId": "325462",

"channelId": "49893",

"allChannelsOfGroup": ["36272"],

"allGroupsOfChannel": ["236726"]

}

✔ Событие добавления связи группа-оператор

POST $webhookUrl

{

"type": "GroupOperatorRelationCreated",

"id": "d73e0aae-8f55-487e-892e-ef645968d7f2",

"createdAt": UnixTimestamp,

"groupId": "325462",

"operatorId": "554432",

"allOperatorsOfGroup": ["554432", "553254"],

"allGroupsOfOperator": ["325462", "236726"]

}

✔ Событие удаления связи группа-оператор

POST $webhookUrl

{

"type": "GroupOperatorRelationDeleted",

"id": "d73e0aae-8f55-487e-892e-ef645968d7f2",

"createdAt": UnixTimestamp,

"groupId": "325462",

"operatorId": "554432",

"allOperatorsOfGroup": ["553254"],

"allGroupsOfOperator": ["236726"]

}