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
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:
|
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:
|
userIdentify() | It identifies the user by the passed parameters. The method gets the parameters:
Deprecated (version 1.0):
|
getChatToken() | Displays the initiated chat token |
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" } ] ] });
Example for getting a token:
window.__usedeskWidgetInitedCallback = function() { let token = window.usedeskMessenger.getChatToken(); console.log(token); }
The widget can be automatically initialized if the following callback has already appeared in the code of the page by then:
window.__widgetInitedCallback = function (widget) { var expectedWidget = window.usedeskMessenger; expectedWidget.identify({ email: 'bob@email.ru', phone: '+7911111111111', name: 'Bob Marly' }); }
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.
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 |
---|---|
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.
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.
window.usedeskMessenger.setAdditionalFields( [ { id: 3840, value: "Text" }, { id: 4704, value: "Checkbox" }, [ { id: 4011,value: "Nested list" } ] ] )
Widget's buttons
It is possible to add buttons to the widget conversation by transmitting specific parameters in the messsage.
Parameters
* 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:
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:
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