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

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

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

Parameter	Description
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'})

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

Parametr	Value
message	The 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
1window.usedeskMessenger.sendMessage({message:"Any text"})

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: "Вложенный список"
            }
        ]
    ]
)

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

* required fields

Parameter	Value
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 "Button text color in messages" and "Button background color in messages"). 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}}

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

Widget

Connecting the widget

Widget methods

Initializing a message from a client

Widget's methods

Request example

1

Changing an additional fields

Widget's buttons

Parameters

Widget item identifiers