Widget

Warning

If you use the on-premise Usedesk version on your own server, then the URL of your methods will be different. Specify the URL to work with API by contacting our support team - support@usedesk.ru

Connecting the widget

You can interact with the widget through a global object: window.usedeskMessenger

It is initialized (connects to the server, gets the necessary data) automatically. 

Widget methods

ParameterDescription
open()It just opens a widget
open('chat')

It allows you to open the widget on a specific screen (or link) which is passed at the parameters:

  • chat
  • docs-search
  • callback
  • whatsapp
  • tg
  • viber
  • ok
  • vk
  • instagram
  • skype
  • facebook 
close()Close the widget
openChat()

Open the chat

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

openDocs()

Open the knowledge base

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

openCallback()

Open the feedback form

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

openWhatsapp()

Open WhatsApp

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

closeChat()

Close the chat (and so far any form)

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

closeDocs()

Close the knowledge base

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

closeCallback()

Close the feedback form

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

closeWhatsapp()

Close WhatsApp

Deprecated (version 1.0): We do not recommend using it. Work with the open action moved to the open parameter.

toggle()

It hides the widget from the user's browser or shows it depending on the switch value.

The method gets the parameters:

  • true
  • false
userIdentify()

It identifies the user by the passed parameters.

The method gets the parameters:

  • name
  • email
  • phone
  • signature - a signature that uniquely identifies the user and his chat on any device. To save the history of correspondence.

    • The signature must be unique for the chat client (e.g. hash of 64 characters).

    • If client changes name, phone number or e-mail, it must not affect the signature because of point 1.

  • additional_fields - an array of data with the id parameters of the additional field and its values, which will be filled in when creating a request.
    Supports any type of additional field: text, checkbox, drop-down list, nested list.
    • Pass the nested list as a separate array (see request example)



Request example
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"
            }
        ]
    ]
});

The widget can be automatically initialized if the following callback has already appeared in the code of the page by then:

Request example
window.__widgetInitCallback = function (widget) {
	var expectedWidget = window.usedeskMessenger;
	expectedWidget.identify({ 
		email: 'bob@email.ru',
		phone: '+7911111111111',
		name: 'Bob Marly' 
		signature: 'SERVER_GENERATED_SIGNATURE'
		});
}

If you don't go the first way (via window.__widgetInitCallback), but you send a direst request (see it below), make sure that the user have not clicked and opened the chat before the user's data becomes available, so you will be able to transmit it via userIdentify

In such cases we recommend you to conceal and display the widget only after the user's data becomes available and you can transmit it to the widget.

Request example
window.usedeskMessenger.userIdentify({name: 'Dwight Schrute', email: 'dwight@mail.ru', phone: '79222222222'})

Initializing a message from a client

Method for sending messages to the widget with its opening-creating a chat:window.usedeskMessenger.sendMessage

Widget's methods

Parametr
Value
messageThe text that will be sent to the widget on behalf of the current client

If you need to specify the mail, the system will wait until the chat window opens and immediately send a message.

Request example


1

window.usedeskMessenger.sendMessage({message:"Any text"})

Changing an additional fields


Use method for changing already existing fields in the request window.usedeskMessenger.setAdditionalFields"

Use the method when you pass values into an existing query. The values you pass will be updated for the current query.

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

Widget's buttons

It is possible to add buttons to the widget conversation by transmitting specific parameters in the messsage.

Parameters

* required fields

ParameterValue
button*Button service ID

{text}*

Any text to appear on the button. At exceeding of the widget width the text is truncated automatically. 
{URL}URL embedded into the button text, so it opens in the browser when clicked. If empty, the button text will automatically be copied and sent as the client reply (for instance, to trigger the bot).
{URL type}

It accepts one of the two values: 

  • blank
  • self

Thus, it also says where the URL will be opened, either new or current browser tab consequently.

If the URL parameter is not set, this one will also be ignored.  

{visibility}

Here you can define whether the button text must be added to the bot message (if there is any) or not.

It accepts one of two values:

  • show
  • noshow

The part of the text enclosed into brackets with noshow will be displayed on the button only:

Sent: Take the gun Vincent  {{button:Take the gun;;;noshow}}

Dispayed: Vincent "Take the gun"

The part of the text taken into brackets with show, will not affect the original text:

Sent: Take the gun Vincent {{button:Take the gun;;;show}}

Displayed: Take the gun Vincent "Take the gun"

In the case of any error of the button configuration it will not appear in the widget. 

Text and button colors are configured on the widget settings page (see ". If none of them are set manually, default colors will be displayed instead.

Example: Take the gun Vincent {{button:Take the gun;https://usedesk.ru;blank;show}}

Widget item identifiers


To collect statistics or customize a widget, you can refer to various elements of the widget through their unique identifiers:

  • The widget icon itself - uw-main-button
  • Widget close button - uw-main-button-close
  • Button to close the chat window when chatting is active - uw-close-chat-button
  • Is the task complete? - uw-task-solved-button
  • Submit button - uw-message-submit-button
  • Attachment button - uw-attachment-button
  • Each of the possible channel buttons:
    • 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',
  • Sending e-mail button when chatting starts - uw-send-email-button
  • Pressing the "Back" button and the "Write to us" button while viewing an article in the knowledge base:
    • uw-button-docs-write
    • uw-button-docs-back