Виджет

Внимание

Если вы используете коробочную версию Юздеска на собственном сервере, то URL методов у вас будет отличаться. Уточните URL для работы с API у поддержки — support@usedesk.ru.

Подключение виджета

С виджетом можно взаимодействовать через глобальный объект: window.usedeskMessenger

Инициализируется (подключается к серверу, получает нужные данные) он автоматически. 

Методы виджета

ЗаголовокОписание
open()Просто открывает виджет
open('chat')

Позволяет открывать виджет на определенном экране(либо ссылке), переданном в параметрах:

  • chat
  • docs-search
  • callback
  • whatsapp
  • tg
  • viber
  • ok
  • vk
  • instagram
  • skype
  • facebook 
close()Закрывает виджет
openChat()

Открыть чат

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр open

openDocs()

Открыть базу знаний

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр open

openCallback()

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

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр open

openWhatsapp()

Открыть вацап

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр open

closeChat()

Закрыть чат (и пока тоже любую форму)

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр close

closeDocs()

Закрыть базу знаний

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр close

closeCallback()

Закрыть форму обратной связи

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр close

closeWhatsapp()

Закрыть вацап

Deprecated (версия 1.0): Не рекомендуем использовать. Работа с действием открытия вынесена в параметр close

toggle()

Скрывает виджет с браузера пользователя либо показывает его в зависимости от значения переключения

Метод принимает параметры:

  • true
  • false
userIdentify()

Идентифицирует пользователя по переданным параметрам.

Метод принимает параметры:

  • name - имя клиента
  • email - почта клиента
  • phone - телефон клиента
  • token - подпись, однозначно идентифицирующая пользователя и его чат на любых устройствах для сохранения истории переписки. (генерирует наша система,  ограничение не меньше 64 символа). 
    • Чтобы получить токен чата для использования метода userIdentify() необходимо выполнить команду window.usedeskMessenger.getChatToken()
  •  additional_fields - массив данных с параметрами id дополнительного поля и его значения, которые заполнятся при создании запроса. Поддерживает любой тип дополнительного поля: текст, флажок, раскрывающийся список, вложенный список.
    • Вложенный список передавайте отдельным массивом (см. пример запроса)

Deprecated (версия 1.0)

  • signature - подпись, однозначно идентифицирующая пользователя и его чат на любых устройствах. Для сохранения истории переписки. 
    • Сигнатура должна быть уникальной для клиента-чата(ограничение не меньше 64 символа)

    • Если клиент меняет имя, номер телефона или емэйл, то это не должно влиять на сигнатуру в силу п1.

getChatToken()

Отображает токен инициированного чата

Пример запроса
window.usedeskMessenger.userIdentify(
{
	name: 'Rad test',
	email: 'rad@test.test',
	phone: '79222222666',
	additional_fields:
	[
    	{
			id: 3840, value: "текст"
		}, 
    	{
			id: 3841, value: "флажок"
		},
    	{
			id: 4704, value: "раскрывающийся список"
		},
    	[
			{
				id: 4011, value: "Вложенный список 1"
			},
			{
				id: 4012, value: "Вложенный список 2"
			},
			{
				id: 4013, value: "Вложенный список 3"
			}
		]
	]
}); 

Пример для получения token:

Пример запроса
window.__usedeskWidgetInitedCallback = function() {            

  let token = window.usedeskMessenger.getChatToken();            

  console.log(token);        

}

Виджет может автоматически проинициализироваться, если в коде страницы к моменту подключения виджета уже будет существовать такой callback:

Пример запроса
window.__widgetInitCallback = function (widget) {
	var expectedWidget = window.usedeskMessenger;
	expectedWidget.identify({ 
		email: 'bob@email.ru',
		phone: '+7911111111111',
		name: 'Bob Marly' 
		});
}

Если же вы не  используете первый способ (через window.__widgetInitCallback), то при использовании прямого вызова(ниже) будьте уверены в том, что пользователь не успеет кликнуть и открыть чат до того, как вам станут известны его данные и вы сможете прокинуть их в чат через прямой вызов identify.

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

Пример запроса
window.usedeskMessenger.userIdentify({name: 'Dwight Schrute', email: 'dwight@mail.ru', phone: '79222222222'})

Инициализация сообщения от клиента

Метод для отправки сообщений в виджет с его открытием-созданием чата: window.usedeskMessenger.sendMessage

Методы виджета

ЗаголовокОписание
messageТекст который будет отправлен в виджет от лица текущего клиента

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

Пример запроса
window.usedeskMessenger.sendMessage({message:"Какой-то текст"})

Изменение дополнительных полей

Метод для изменения уже существующих полей в запросе window.usedeskMessenger.setAdditionalFields

Используйте метод при передаче значений в уже существующий запрос. Значения, которые вы передаете, обновятся к текущем запросе

Пример запроса
window.usedeskMessenger.setAdditionalFields(
    [
        {
            id: 3840, value: "текст"
        },
        {
            id: 4704, value: "флажок"
        },
        [
            {
                id: 4011,value: "Вложенный список"
            }
        ]
    ]
)

Кнопки в виджете

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

Параметры

* обязательные поля 

ПараметрЗначение
button*Служебный идентификатор кнопки

{текст}*

Любой текст кнопки. При превышении ширины виджета текст обрезается
{ссылка}URL перехода клика по кнопке. Если параметр пустой, то клик по кнопке отправляет сам текст кнопки в ответ(например, чтобы вызвать ответ бота)
{тип ссылки}

Может принимать одно из двух значений:

  • blank
  • self

Говорит где открывать ссылку — в новом или текущем окне соответственно

Если URL не заполнен, значение параметра игнорируется

{видимость}

Показывать или не показывать текст из кнопки в самом тексте(если он там есть)

Может принимать одно из двух значений:

  • show
  • noshow

Если в тексте передать так же текст кнопки и у кнопки указать noshow, то текст будет только показываться на кнопке.

Отправили: Возьми дробовик Винсент {{button:Возьми дробовик;;;noshow}}

Получили: Винсент "Возьми дробовик"

Если в тексте передать что-то и указать show, то кнопка не повлияет на исходный текст

Отправили: Возьми дробовик Винсент {{button:Возьми дробовик;;;show}}

Получили: Возьми дробовик винсент "Возьми дробовик"

В случае, если произошла ошибка в конфигурировании кнопки - кнопка и её настройки не будут отображены в виджете.

Цвет текста и фона кнопки конфигурируются на странице настроек виджета ("Цвет текста кнопки в сообщениях" и "Цвет фона кнопки в сообщениях"). При этом включены цвета по умолчанию, если параметры не заданы.

Пример: Возьми дробовик Винсент {{button:Возьми дробовик;https://usedesk.ru;blank;show}}

Идентификаторы элементов виджета

Для сбора статистики или кастомизации виджета можно обращаться к различным элементам виджета через их уникальные идентификаторы:

  • Сама иконка виджета - uw-main-button
  • Кнопка закрытия виджета - uw-main-button-close
  • Кнопка закрытия окна чата при активном чате - uw-close-chat-button
  • Кнопка "Задача завершена?" - uw-task-solved-button
  • Кнопка отправки сообщения - uw-message-submit-button
  • Кнопка вложения - uw-attachment-button
  • Каждая из возможных кнопок каналов:
    • id: 'uw-button-facebook',
    • id: 'uw-button-telegram',
    • id: 'uw-button-ok',
    • id: 'uw-button-viber',
    • id: 'uw-button-vk',
    • id: 'uw-button-skype',
    • id: 'uw-button-whatsapp',
    • id: 'uw-button-instagram',
  • Кнопка отправки имэйла при начале диалога в чате - uw-send-email-button
  • Нажатие на кнопку "Назад" и на кнопку "Написать нам" при просмотре статьи в базе знаний:
    • uw-button-docs-write
    • uw-button-docs-back