Widget connection and methods

Widget connection

You can interact with the widget through the global object: window.usedeskMessenger
It initializes (connects to the server, gets the necessary data) automatically.

Widget methods

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() Closes the widget
openChat()

Opens chat

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

openDocs()

Opens knowledge base

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

openCallback()

Opens feedback form

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

openWhatsapp()

Opens WhatsApp

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

closeChat()

Closes 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()

Closes the knowledge base

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

closeCallback()

Closes the feedback form

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

closeWhatsapp()

Closes WhatsApp

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

toggle()

Hides the widget from the user's browser or displays it depending on the switching value.

The method accepts values:

  • true
  • false
userIdentify()

It identifies the user by the passed parameters.

The method gets the parameters:

  • name
  • email
  • phone
  • token — an character sequence that uniquely identifies the user and his chat on any device to save the history of conversations. Token is generated by our system automatically, at leats 64 symbols
    • to get a chat token for the userIdentify() method, you must run the command window.usedeskMessenger.getChatToken()
  • additional_fields — an array of data with the IDs of additional fields and its values, which will be saved to ticket upon creation.
    Supports any type of additional field: text, checkbox, drop-down list, nested list.
    • Pass the nested list as a separate array (see request example)
    N.B.: Identification data is sent to Usedesk only when the client initiates a chat within a single browser session

N.B.2: If Usedesk already has data about the client, the useridentify() method will not change the client's data

getChatToken()

Returns the initiated chat token

Request example
window.usedeskMessenger.userIdentify(
{
    name: 'Rad test',
    email: 'rad@test.test',
    phone: '79222222666',
    additional_fields:
    [
        {
            id: 3840, value: "text"
        },
        {
            id: 3841, value: "checkbox"
        },
        {
            id: 4704, value: "drop-down list"
        },
        [
            {
                id: 4011, value: "Nested list 1"
            },
            {
                id: 4012, value: "Nested list 2"
            },
            {
                id: 4013, value: "Nested list 3"
            }
        ]
    ]
});

You can identify the client before initiating the chat. To do this, use the callback window.__widgetInitCallback. It is sent when widget appears on page.

Callback usage example
window.__widgetInitCallback = function (widget) {
    var expectedWidget = window.usedeskMessenger;
    expectedWidget.identify({ 
        email: 'bob@email.ru',
        phone: '+7911111111111',
        name: 'Bob Marly' 
        });
}
If you're not using window.__widgetInitCallback identification, when using a direct call, be sure that the user won't click on widget and open the chat before you know the user's data.
In this case it is recommended to hide the widget and show it only when the user's data are known and you call the corresponding call.
You should use callback window.__usedeskWidgetInitedCallback to execute code after chat initialization, when user has opened chat in widget. An example to get the token:
Retrieving token request example
window.__usedeskWidgetInitedCallback = function() {            
  let token = window.usedeskMessenger.getChatToken();            
  console.log(token);        
}

You can use callback window.__usedeskWidgetMessageInClosedWidgetCallback to perform actions when a new message received in the minimized initialized chat from an agent. An example of using:

Callback usage example
window.__usedeskWidgetMessageInClosedWidgetCallback = () => console.log('New message received in the minimized initialized chat');