Виджет
Внимание
Если вы используете коробочную версию Юздеска на собственном сервере, то URL методов у вас будет отличаться. Уточните URL для работы с API у поддержки — support@usedesk.ru.
Подключение виджета
С виджетом можно взаимодействовать через глобальный объект: window.usedeskMessenger
Инициализируется (подключается к серверу, получает нужные данные) он автоматически.
Методы виджета
Заголовок | Описание |
---|---|
open() | Просто открывает виджет |
open('chat') | Позволяет открывать виджет на определенном экране(либо ссылке), переданном в параметрах:
|
close() | Закрывает виджет |
toggle() | Скрывает виджет с браузера пользователя либо показывает его в зависимости от значения переключения Метод принимает параметры:
|
userIdentify() | Идентифицирует пользователя по переданным параметрам. Метод принимает параметры:
|
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 перехода клика по кнопке. Если параметр пустой, то клик по кнопке отправляет сам текст кнопки в ответ(например, чтобы вызвать ответ бота) |
{тип ссылки} | Может принимать одно из двух значений:
Говорит где открывать ссылку — в новом или текущем окне соответственно Если URL не заполнен, значение параметра игнорируется |
{видимость} | Показывать или не показывать текст из кнопки в самом тексте(если он там есть) Может принимать одно из двух значений:
Если в тексте передать так же текст кнопки и у кнопки указать 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* | Переменная, в которую добавится указанная в поле информация Возможные значения:
Также можно использовать id дополнительного поля. В него будет записано значение, указанное клиентом. Поддерживаются следующие типы дополнительных полей:
|
required | Является ли поле обязательным Возможные значения:
Значение по умолчанию: 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