Содержание статьи:

• Введение
• Типы данных
• Перечисления
• События
• Методы

Введение

LiveTex предоставляет API для работы в виджетами.

Объект LiveTex и его методы реализованы непосредственно в коде виджета, который загружается стандартным кодом вставки LiveTex.
Асинхронная загрузка виджета не позволяет точно предсказать момент окончания его инициализации. Для того чтобы быть уверенным в наличии виджета на странице и в готовности всех методов, в коде вставки следует предопределить объект LiveTex, в котором определить обработчик события onLiveTexReady. 

Типы данных

• ConversationAttribute
• VisitorAttribute
• Contact
• Employee
• EmployeeFilter
• Schedule

ConversationAttribute

Атрибут обращения.

Присваивается при вызове метода setConversationAttributes

Тип

{key: string, value: string, is_hidden: boolean, type: number}

VisitorAttribute

Атрибут посетителя чата.

Присваивается при указании посетителем контактных данных или при помощи метода setVisitorAttributes

Тип

{ name: LiveTex.VisitorDisplayedName, contacts: !Array.<LiveTex.Contact> }

Contact

Контактные данные посетителя чата.

Заполняется посетителем в форме обратной связи или при помощи метода setVisitorAttributes

Тип

{value: string, type: LiveTex.ContactType}

Employee

Оператор на которого назначен чат

Тип

{ id: string, name: string, avatar_url: string, status: LiveTex.EmployeeStatus, is_available: boolean}

EmployeeFilter

Оператор

Тип

{ status: !Array.<LiveTex.EmployeeStatus>, is_available: boolean, department_id: string}

Schedule

График работы операторов, принимающих звонки x-widget

Тип

{ from: number, to: number, days: !Array.<number> }

Перечисления

• Event
• EmployeeStatus
• ContactType
• ConversationAttributeType
• SourceType
• WidgetType

Event

Набор событий, на которые можно подписаться.

Каждый обработчик события должен принимать объект со свойствами 'event' - тип события и 'data' - данные события

EmployeeStatus

Возможные статусы оператора

ContactType

Тип контактных данных посетителя

ConversationAttributeType

Типы атрибутов обращения

SourceType

Автор действия или события

WidgetType

Типы виджета

События

• LIVETEX_READY
• CALL_ESTABLISHED
• CALL_STARTED
• CONVERSATION_STARTED
• CONVERSATION_CLOSED
• EMPLOYEE_MESSAGE_SENT
• INVITATION_WINDOW_CLOSE
• INVITATION_WINDOW_SHOWN
• OFFLINE_MESSAGE_SENT
• CALLBACK_SENT
• WELCOME_WINDOW_SHOWN
• X_WINDOW_SHOWN

LIVETEX_READY

Событие завершения загрузки виджета на сайте.

Функция будет вызвана сразу после завершения инициализации LiveTex widgets API.

Подписываться на событие onLiveTexReady на странице нужно только один раз. Если на странице будет несколько отслеживаний события onLiveTexReady, то сработает только одно. Если по факту готовности LiveTex необходимо выполнить несколько дейтсвий, то следует все выполнять в одном стэке.

Пример:

<script>
var LiveTex = {
    onLiveTexReady: function() {
        // код, выполняемый после инициализации LiveTex Widgets API
        console.log("Виджет загрузился на сайте!");
    }
};
</script>

CALL_ESTABLISHED

Cобытие ответа на звонок

Уведомляет о том, что связь между оператором и посетителем успешно уставлена. Не несет информацию о дальнейшем развитии звонка и о его завершении

Данные

event: 'call-established'

Пример

function onCallEstablished() { 
 console.log('С клиентом созвонились');
} 

var descriptor = LiveTex.addEventListener(
LiveTex.Event.CALL_ESTABLISHED, onCallEstablished);

CALL_STARTED

Cобытие нажатия на кнопку начала звонка

Обычно событие возникает по нажатию кнопки "Да, позвоните мне" в окне X-Widget или по нажатию на X-кнопку

Данные

event: 'call-started'

Пример

function onCallStarted() {
 console.log('Клиент хочет, чтоб ему позвонили');
 }

 var descriptor = LiveTex.addEventListener(
 LiveTex.Event.CALL_STARTED, onCallStarted);

CONVERSATION_STARTED

Событие начала обращения

Срабатывает при начале чата, отправке Формы обратной связи или Заказе звонка

Данные

event: 'conversation-started'

Пример

function onConversationStarted(event){
 var data = event['data']; var source = event['data']['source'] || {};
 var sourceType = source['type'];

 if (sourceType === LiveTex.SourceType.VISITOR) {
   alert('Обращение началось с сообщения посетителя');
 } else if (sourceType === LiveTex.SourceType.EMPLOYEE) {
   alert('Обращение началось с приглашения оператора');
 } else if (sourceType === LiveTex.SourceType.SYSTEM) {
   alert('Обращение началось с вовлечения');
 } else if (sourceType === LiveTex.SourceType.API) {
   alert('Обращение началось после вызова метода API'); }
 } 

var descriptor = LiveTex.addEventListener(
 LiveTex.Event.CONVERSATION_STARTED, onConversationStarted);

CONVERSATION_CLOSED

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

Данные

event: 'conversation-closed'

Пример

function onConversationClosed(event) {
  var data = event['data'];
  alert('Обращение ' + data.conversation_id + ' закрыто');
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.CONVERSATION_CLOSED, onConversationClosed);

EMPLOYEE_MESSAGE_SENT

Событие отсылки сообщения посетителю оператором.

Данные

event: 'employee-message-sent'

Пример

function onEmployeeMessageSent(event) {
  alert('Оператор прислал сообщение "' + event['data']['text'] + '".');
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.EMPLOYEE_MESSAGE_SENT, onEmployeeMessageSent);

INVITATION_WINDOW_CLOSE

Уведомляет о том, что посетитель закрыл окно вовлечения (посетитель нажал кнопку закрытия)

Данные

event: 'invitation-window-close'

Пример

function onInvitationClose(event) {
  console.log("Приглашение было отклонено");
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.INVITATION_WINDOW_CLOSE, onInvitationClose);

INVITATION_WINDOW_SHOWN

Описание

Уведомляет о показе окна вовлечения на сайте

Данные

event: 'invitation-window-shown'

Пример

function onInvitationWindowShown(event) {
  var message = event['data']['message'] || '';
  var employee = event['data']['employee'];
  console.log(employee['name'] + ' отправил приглашение: ' + message);
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.INVITATION_WINDOW_SHOWN, onInvitationWindowShown);

OFFLINE_MESSAGE_SENT

Событие отсылки сообщения посетителем через форму обратной связи

Данные

event: 'offline-message-sent'

Пример

function onOfflineMessageSent(event) {
  alert('Оператор отправил офлайн сообщение "' + event['data']['text'] + '".');
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.OFFLINE_MESSAGE_SENT, onOfflineMessageSent);

CALLBACK_SENT

Событие отсылки сообщения посетителем через callback-форму

Данные

event: 'callback-sent'

Пример

function onCallbackSent(event) {
  alert('Оператор отправил заявку "' + event['data']['text'] + '".');
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.CALLBACK_SENT, onCallbackSent);

WELCOME_WINDOW_SHOWN

Событие открытия welcome-window

Уведомляет о показе окна приветствия на сайте

Данные

event: 'welcome-window-shown'

Пример

function onWelсomeWindowShown() {
  console.log('Окно приветствия показано');
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.WELCOME_WINDOW_SHOWN, onWelсomeWindowShown);

X_WINDOW_SHOWN

Событие открытия окна X

Уведомляет о показе окна X-Widget на сайте

Данные

event: 'x-window-shown'

Пример

function onXWindowShown() {
  console.log('X-Widget показано');
}

var descriptor = LiveTex.addEventListener(
  LiveTex.Event.X_WINDOW_SHOWN, onXWindowShown);

Методы

• reinit
• addEventListener
• removeEventListener
• getDepartments
• getEmployees
• hideLabel
• showLabel
• hideActiveWindow
• showActiveWindow
• hideInvitationWindow
• showInvitationWindow
• initiateCall
• isDepartmentAvailable
• isDepartmentOnline
• isInvitationShown
• showWelcomeWindow
• setConversationAttributes
• setVisitorAttributes
• setWelcomeDepartments
• showCallRequestDepartments
• showOfflineDepartments
• showOfflineWindow
• showConversationWindow
• showXWindow

reinit

Описание

Полностью реинициализирует сессию посетителя. Сбрасывает состояние в виджете.

ВНИМАНИЕ! Вызов этого метода при активном чате приведет к его немедленному закрытию. Вернуться к истории переписки посетитель уже не сможет.

Параметры

Пример

function onSuccess() {
    console.log('LiveTex is reinitialized');
 }

 function onFail() {
    console.log('LiveTex is not reinitialized');
 }

 LiveTex.reinit(onSuccess, onFail);

addEventListener

Описание

Регистрирует функцию-обработчик указанного события.

Возвращает дескриптор, который можно использовать для удаления обработчика в методе LiveTex.removeEventListener()

Возможна регистрация нескольких обработчиков на одно событие путем повторного вызова этого метода

Параметры

Пример

function onConversationStarted(data) {
  alert('Общение началось');
 }

 var descriptor = LiveTex.addEventListener(
  LiveTex.Event.CONVERSATION_STARTED, onConversationStarted);

function onConversationStarted(data) {
  alert('Общение началось');
 }

 // Регистрация обработчика
 var descriptor = LiveTex.addEventListener(
    LiveTex.Event.CONVERSATION_STARTED, onConversationStarted);

 // Удаление обработчика
 LiveTex.removeEventListener(
    LiveTex.Event.CONVERSATION_STARTED, descriptor);

getDepartments

Запрашивает список отделов, настроенных на точку контакта.

Параметры

Пример

LiveTex.getDepartments(function(data) {
    for(var i=0; i < data.length; i++) {
      alert('Название отдела: ' + data[i].name);
    }
 });

getEmployees

Возвращает список операторов. Может возвращать список, отфильтрованный по определенным критериям

Параметры

Пример

// выбрать всех онлайн операторов
LiveTex.getEmployees(
    function(employeeList) { console.log(employeeList) },
    console.warn.bind(console),
    { status: [LiveTex.EmployeeStatus.ONLINE, LiveTex.EmployeeStatus.BUSY] }
);

// выбрать всех доступных операторов в отделе
LiveTex.getEmployees(
    function(employeeList) { console.log(employeeList) },
    console.warn.bind(console),
    { is_available: true, departmentId: '16429' }
);

hideLabel

Скрывает ярлык чата.

Метод не имеет параметров и не возвращает значения.

Пример

LiveTex.hideLabel();

showLabel

Отображает ярлык чата.

Метод не имеет параметров и не возвращает значения.

Пример

LiveTex.showLabel();

hideActiveWindow

Скрывает открытое на текущий момент окно

(диалоговое окно, offline окно, окно приветствия, форма жалобы, форма заказа звонка)

Пример

LiveTex.hideActiveWindow();

showActiveWindow

Открывает активное на текущий момент окно из ярлыка

(диалоговое окно, offline окно, окно приветствия, форма жалобы, форма заказа звонка)

Пример

LiveTex.showActiveWindow();

hideInvitationWindow

Закрывает окно вовлечения.

Метод не имеет параметров и не возвращает значения.

Пример

LiveTex.hideInvitationWindow();

showInvitationWindow

Отображает окно вовлечения. Можно указать определённого оператора или отдел. При указании '*' вместо departmentId или employeeId выберется любой оператор/группа. Если в момент вызова метода на сайте нет доступного оператора, будет вызван обработчик ошибки.

Параметры

Пример

LiveTex.showInvitationWindow(
    function(employee) { console.log('Окно вовлечения открыто') },
    function(error) { console.error(error); },
    '*', '*',
    'Нужна помощь?'
);

initiateCall

Инициализация звонка x-widget

Параметры

При указании отдела, значение параметра employeeId будет проигнорировано

Пример

// Инициируем звонок на номер '+7(912)1234567'
LiveTex.initiateCall(
    function() { console.log('Звоним...'); },
    function(error) { console.log('Ошибка ' + error); },
    '+7(912)1234567',
    '*',
    '*'
);

// Звонок определённым операторам
LiveTex.initiateCall(
    function() { console.log('Звоним...'); },
    function(error) { console.log('Ошибка ' + error); },
    '+7(912)1234567',
    '21571,21572',
    '*'
);

// Звонок определённому отделу
LiveTex.initiateCall(
    function() { console.log('Звоним...'); },
    function(error) { console.log('Ошибка ' + error); },
    '+7(912)1234567',
    '*',
    '16500'
);

isDepartmentAvailable

Возвращает флаг доступности отдела.

Если в отделе нет операторов онлайн или все операторы имеют очередь обращений, достигшую установленного лимита, метод вернёт false.

Параметры

Пример

LiveTex.isDepartmentAvailable('123123', function(isAvailable) {
    if (isAvailable) {
      alert('Операторы отдела 123123 доступны для нового обращения');
    }
 });

isDepartmentOnline

Возвращает статус отдела. Если в отделе хотя бы один оператор online - вернёт true

Параметры

Пример

LiveTex.isDepartmentOnline('123123', function(isOnline) {
    if (isOnline) {
      alert('В данный момент в отделе есть online-операторы');
    }
 });

isInvitationShown

Проверяет состояние окна вовлечения отображено/скрыто

Возвращает true, если окно вовлечение отображено, false - если окно вовлечения скрыто

Пример

var isShown = LiveTex.isInvitationShown();

showWelcomeWindow

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

Пример

LiveTex.showWelcomeWindow();

setConversationAttributes

Устанавливает атрибуты обращению.

Переданные атрибуты будут отображены в Информации по обращению в Приложении оператора и в Истории в Личном кабинете.

Если название установленного пречат поля совпадает с названием видимого посетителю пречат поля, то в Рабочем месте оператора будет отображаться то значение, которое посетитель ввел в соответствующее пречат поле.

Параметры

Пример

LiveTex.setConversationAttributes(
   {'VIP клиент': 'Да', 'Артикул товара:': 'QW123456'},
   {'client_id': '12345'});

setVisitorAttributes

Устанавливает атрибуты посетителя, заполняет валидные значения в формы.

Параметры

Пример

LiveTex.setVisitorAttributes(
  function() { console.log('атрибуты сохранены'); },
  function(error) { console.log('Ошибка: ' + error); },
  {
    name: { 'name': 'Покупатель', 'is_editable': false },
    contacts: [{
      'value': 'mail@example.ru',
      'type': LiveTex.ContactType.EMAIL
    }, {
      'value': '+7(912)765-4321',
      'type': LiveTex.ContactType.PHONE
    }]
  }
);

LiveTex.setVisitorAttributes(
  function() { console.log('атрибуты сохранены'); },
  function(error) { console.log('Ошибка: ' + error); },
  {
    name: { name: 'Покупатель', is_editable: true },
    contacts: []
  }
);

setWelcomeDepartments

Устанавливает набор отделов, которые будут показаны посетителю в выпадающем списке окна приветствия.

В выпадающем окне будут отображены только те отделы, в которых есть доступные операторы. Если среди установленных отделов нет отделов с доступными операторами, то, при открытии окна посетителем, будет отображена оффлайн форма

Параметры

Пример

LiveTex.setWelcomeDepartments(['123', '124'], function() {
  alert('Группа назначена');
 });

showCallRequestDepartments

Отображает селектор групп в форме заказа звонка

Параметры

Пример

// позволяет выбрать группу в форме заказа звонка
LiveTex.showCallRequestDepartments();

// предустанавливает группу в форме заказа звонка
LiveTex.showCallRequestDepartments([{ "id": "16429", "name": "Отдел продаж"}]);

// позволяет выбрать группу из предустановленных
LiveTex.showCallRequestDepartments([
  { "id": "16429", "name": "Отдел продаж"},
  { "id": "16430", "name": "Тех поддержка"}
]);

showOfflineDepartments

Отображает селектор групп в офлайн форме

Параметры

Пример

// позволяет выбрать группу при отправке оффлайн формы
LiveTex.showOfflineDepartments();

// предустанавливает группу при отправке оффлайн формы
LiveTex.showOfflineDepartments([{ "id": "16429", "name": "Отдел продаж"}]);

// позволяет выбрать группу из предустановленных
LiveTex.showOfflineDepartments([
  { "id": "16429", "name": "Отдел продаж"},
  { "id": "16430", "name": "Тех поддержка"}
]);

showOfflineWindow

Открывает форму обратной связи.

Пример

LiveTex.showOfflineWindow();

showConversationWindow

Открывает диалоговое окно обращения.

При вызове метода можно рекомендовать определённого оператора или отдел. При указании '*' вместо departmentId или employeeId выберется любой оператор/группа. Если в момент вызова метода на сайте нет ни одного доступного оператора, откроется форма обратной связи. При этом в complete вернётся null.

Обратите внимание: при подключенном Боте, метод выполняться не будет. Для открытия окна с Ботом воспользуйтесь методом showActiveWindow

Параметры

Пример

LiveTex.showConversationWindow(
    function(employee) {
        console.log(employee ?
          'Открыт диалог с оператором ' + employee.name :
          'Открыто оффлайн окно');
    },
    function(error) { console.error(error); },
    '*', '16429',
    'Первое сообщение'
);

showXWindow

Открывает модальное окно X-Window

Параметры

Пример

// открывает X-Window, звонит только с пн-пт с 9 до 18 часов
LiveTex.showXWindow(
    function(){console.log('X-Window открыто')},
    function(error){console.error(error)},
    { days: [0,1,2,3,4], from: 9*3600, to: 18*3600}
);

// открывает X-Window с назначением на определённого оператора
// с указанным сообщением
LiveTex.showXWindow(
    function(){console.log('X-Window открыто')},
    function(error){console.error(error)},
    { days: [0,1,2,3,4], from: 9*3600, to: 18*3600},
    [21572],
    'Оставьте свой номер телефона и мы перезвоним Вам'
);

// открывает X-Window с предустановленным телефоном
LiveTex.showXWindow(
    function(){console.log('X-Window открыто')},
    function(error){console.error(error)},
    { days: [0,1,2,3,4], from: 9*3600, to: 18*3600},
    null, null,
    '+7(912)654-54-54'
);