Содержание
Введение
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": "Текстовое сообщение оператору"
}
Может быть указан параметр groupId или operatorId для маршрутизации, соответственно, на конкретную группу или оператора. Если указаны оба параметра, то это приведёт к маршрутизации собеседника на оператора в контексте указанной группы. Если ни один параметр не указан, то коммуникационная платформа сама выберет куда перенаправить обращение собеседника. Поля visitorEmail и 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"]
}
Комментарии