Виджет

Created by Василий

Внимание

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

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

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

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

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

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

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

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

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

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

  • true
  • false
userIdentify()

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

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

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


Идентифицировать клиента можно до инициации чата. Для этого следует воспользоваться колбэком (callback) window.__widgetInitCallback: 

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

Если вы не используете идентификацию через window.__widgetInitCallback, то при использовании прямого вызова будьте уверены в том, что пользователь не успеет кликнуть и открыть чат до того, как вам станут известны его данные.

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


Для выполнения кода после инициализации чата следует использовать коллбэк (callback) window.__usedeskWidgetInitedCallback. Пример для получения token:

Пример запроса
window.__usedeskWidgetInitedCallback = function() {            
  let token = window.usedeskMessenger.getChatToken();            
  console.log(token);        
}

Коллбэк (сallback) на первое сообщение от клиента

Callback поможет отследить, когда клиента напишет первое сообщение в виджет. 

Пример запроса
window.__usedeskWidgetFirstClientMessageCallback = () => console.log('callback первого сообщения')


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

Метод для отправки сообщений в виджет с его открытием-созданием чата: 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}}

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

Возьми дробовик Винсент {{button:Возьми дробовик}}

{{button:Возьми дробовик}}

Формы в виджете

С помощью форм в чате виджета вы можете запросить дополнительные данные у клиента: e-mail, телефон, имя, должность или любую информацию в текстовом виде

Конструктор полей в форме
{{form;{name};{associate};{required}}}

Параметры

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

ПараметрЗначение
form*Служебный идентификатор формы
name*Заголовок поля
associate*

Переменная, в которую добавится указанная в поле информация

Возможные значения: 

  • email — почта клиента;
  • phone — телефон клиента;
  • name — имя клиента;
  • note — заметка клиента;
  • position — должность клиента

Также можно использовать id дополнительного поля. В него будет записано значение, указанное клиентом.

Поддерживаются следующие типы дополнительных полей:

  • Текст;
  • Флажок;
  • Раскрывающийся список;
  • Вложенный список
required

Является ли поле обязательным

Возможные значения:

  • true — обязательно;
  • false — необязательно

Значение по умолчанию: false

В случае, если произошла ошибка в конфигурировании поля, оно не будет отражено в виджете

Примеры использования полей форм



Пример исходящего сообщения
Привет! Хотим узнать немного больше о тебе и заказе {{form;Имя и Фамилия;name;true}} {{form;Почта;email;true}} {{form;Телефон;phone}} {{form;Название товара;135793}}


{{form;Имя и Фамилия;name;true}} — Поле с заголовком "Имя и Фамилия", данные будут записаны в качестве имени клиента, является обязательным;

{{form;Почта;email;true}} — Поле с заголовком "Почта", данные будут записаны в качестве почты клиента, является обязательным;

{{form;Телефон;phone}} — Поле с заголовком "Почта", данные будут записаны в качестве телефона клиента, является необязательным;

{{form;Название товара;135793}} — Поле с заголовком "Название товара", значение будет добавлено в дополнительное поле с id 135793, является необязательным

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

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

  • Сама иконка виджета - 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