Connection, configuration and widget features


Widget connection

To connect the widget to the site, open the «Channels» → «Add channel».

Then click «Chats».

At the bottom of the settings page you will find the widget code. Once the widget is ready to be published, copy the script and ask your site administrator to place the script before the closing tag. If you place the widget through Google Tag Manager, please follow the instructions.

You can add a widget to your Knowledge base in Usedesk. To do this, copy a widget code and go to «Knowledge base» → «Edit».

Paste a copied widget code into the «Footer scripts» field and click «Save».

Done, the widget will now appear in your Knowledge base!

Widget configuration

The widget adjustment card consists of 9 blocks:

«Widget» block

General widget settings:

  • Name of the channel. Required field. Enter the name of the channel that will be displayed in the general channel list in the "Channels" section and used in Usedesk (filters, ticket card, settings, etc.);
  • Language — the language of system messages and buttons in the widget. Choose the one your clients speak. By default, the system selects the language that is set in a company settings;
  • Color — the main color of the widget for the header and buttons;
  • Text in the header. Required field. Specify the header in the chat header;
  • Powered by — the text at the bottom of the widget, for example, to alert you when personal data is being collected. Displayed in the form of feedback and in chat when the setting is off in the «Chat» — «Do not request mail» block;
  • Allow attachments — check this box to allow clients to send attachments to the chat room;
  • Allow evaluation — select this option if you want the client to have the opportunity to evaluate the dialog in the widget chat. The client will be able to evaluate the quality of support by clicking on the asterisk;
  • Evaluation hint text — the text that will be displayed when you hover over the asterisk. For example, «Is your issue resolved?» or «Evaluate the quality of support»;
  • Display priority (z-index) — the index determines the priority of displaying the widget among layers of other elements of your site. For example, if the widget index is lower than the index of the main image on the site, the widget will not be displayed (the image will be in priority);
  • Show the submit button in a knowledge base section — check this box to activate the feedback button from the «Write to us» widget if the client is reading one of your articles;
  • Delay for missed chats — specify the number of seconds after which the widget's chat will be considered skipped if the operator does not respond to the client. The system must react only to the user's first response in new or reopened chats.

    The time is counted from the moment the client has written the message until the operator's first response. For example: the client has written a message, the user has replied within the time limit set in the configuration, and until the chat is closed, you wouldn't miss this message.

    If the value is blank, the system will automatically transfer the number of seconds to 0, and not a single chat from the widget will be considered missed. The user can continue working with the missed chats in the «Tickets» section of the «Missed Chats» filter (or select the «Missed Chats» filter in the chat);
  • Maximum chats per agent — specify the maximum amount of chats that can be a single agent. The system distributes chat rooms evenly among all agents up to the specified amount in the setting. When the limit is reached, the rest of the chat rooms will remain unassigned.

    However, if there is a rule that includes the assignment action, the assignment will fail when the limit is reached (all other actions of the rule will be followed). The limit refers to allocations by bot or triggers with the «Assign to a next agent» and «Assign to a busy agent» actions, and does not refer to tickets that have been reopened by a client message, assigned to an agent manually, or through the «Update Executor» action.

    If the value is blank, the system will automatically reset the number of chats to zero and the chat distribution will work without limit on the amount of chats;
  • Allowed to answer if a client is offline — check this box so that users can respond to the client, even if they have already left the site and offline. Enable this setting if you are sure that the client will return to the widget soon;
  • Hide when clicking outside the area — tick the box, if you want a widget to minimize when you click outside its area. It is convenient, so that a widget does not interfere with comfort work with the site after contacting the support team. The default setting is turned on;

  • Automatic distribution — the system will assign another agent as the chat assignee if the client writes a message to the chat, and the current assignee will be in the «Offline» status. Usedesk will appoint an agent with the «Online» status with the least number of chats as the assigneer. Read more about automatic distribution at the link;

  • Only allowed to terminate your chats — check this box, and the user will be able to end only the chats assigned to it;
  • Show a widget — choose to display the widget on the site: always, during working hours (working hours of user groups are used) or never;
  • No messages (h) — if no new messages appear in the channel within the specified number of hours, Usedesk will send a notification to the administrators.

Note! For internal security, the Usedesk renames attachments from clients in the following format:

.aru .msc .sfx .tmp .py .pif .application .wmf .msp .com .cmd .dll .apk .bat .bin .cgi .cmd .com .cpp .js .jse .exe .html .hta .htm .vbs .vb .phtml .gadget .gtp .hta .jar .scr .cpl .msi .msu .msp .paf .ps1 .pwz .scr .thm .vb .vbe .vbs .ws .wsc .wsh .wsf .php .jse .ps1 .ps1xml .ps2 .psc1 .psc2 .lnk .inf .scf .msh .msh1 .msh2 .mshxml .msh1xml .msh2hml .reg .doc .xls .ppt .docm .dotm .xlsm .xltm .pptm .potm .ppam .ppsm .sldm .gzquar .zix .ocx .ozd .class .swf .drv .chm .pgm .sjs .xlm .dev .vba .vbe .pif .tsa .vxd .hlp .sop .xnxx .386 .tps .boo .vb .pcx .rhk .bkd .exe1 .dxz .osa .lik .cih .dyz .9 .mfu .z7p .dlb .kcd .dyv .mjz .php3 .dom .hlw .wsc .vbx .fnr .cla .rsc_tmp .wlpginstall .dli .xir .mjf .bhx .mcq .bup .upa .dllx .xdu .xlv .cxq .bxz .ska .wsh .cfxxe .txs .qrn .fag .tti .bll .vexe .xtbl .uzy .smtmp .tko .oar .ceo .scr .smm .plc .cc .ssy .ctbl .spam .dbd .blf .ce0 .iws .zvz .vzr .hsq .rna .aepl .nls .lkh .let .aut .delf .fuj .ezt .buk .bmw .hts .atm .iva .dx .bqf .qit .pr .bps .fjl .capxml .cyw .pid .lpaq5 .lok .xnt .0_full_0_tgod_signed

For example: .doc is renamed to .doc.dangerouse_format.txt

«Button» block

Setting the widget button display:
  • Number of waves — set any value of the field to more than one so that your widget attracts more attention — that's how many times the icon will flash after the page is loaded;
  • Badge show timeout — the number of seconds after which the widget appears on the page where it is installed;
  • Position — position of the widget button on the page: right, left;
  • Colour — the background of the widget button;
  • Icon — download the icon for the widget (picture or GIF) or use the default icon — the Usedesk logo. Possible formats: .png, .jpeg, .webp, .gif, .svg.

«Tooltip» block

Setting up hints in the widget:

  • Show — select the option when you want to display the tooltip in the widget: always, never, when hovering;
  • Background color — the background color of the tooltip;
  • Text — the text of the tooltip for the widget. Enter the tooltip in the language in which your clients communicate;
  • Text color — the color of the hint text;
  • Text size — the size of the hint text.

«Feedback form» block

Setting up the feedback form:

  • Create tickets in the channel — select the e-mail channel through you'll receive the feedback from clients to the «Tickets» section;
  • Show — select the option when you want to display the feedback form in the widget:
    • after hours. The working time of user groups is set up, the rest of the time it is a chat with support;
    • always only feedback form. Chat with support will not be displayed;
    • always feedback form + chat. When you open the widget, the feedback form will be available, and after filling the widget, a chat with support will open;
    • never. Chat with support will always be visible.
  • Form titlespecify the name of the form. If you leave the field blank, the standard «Feedback» will be displayed on the client-side;
  • Greeting — add a greeting text that will be sent to the client on behalf of the company bot when filling out the feedback form. By default, the bot replies as «Usedesk Bot» if the bot is not renamed in the settings. The bot name can also be set in the widget settings in the «Chat» block — «Replace operator name with» and the bot will reply from the name specified in the field. The text can be divided into paragraphs using Enter or the <br/> tag — it needs to be inserted into the line between paragraphs;

  • Topics. Required field. Specify the topics from which the client can choose when contacting you. The topic will become the title of the incoming request;

  • Topic headline — write the text of the help to the client;
  • Topic required — check the box to make the selection of a topic mandatory;
  • Custom fields — fields in the form with any additional information. For example, «city», «order number», etc. Check the box below to make the added fields mandatory;
  • Additional ticket fields — fields that you create in the «Settings» → «Additional fields» section and fill in when working with the ticket. You can output several fields to the feedback form. The completed fields after sending the feedback form will be filled in automatically in the created ticket card. The actions specified in the settings of the additional field will be performed. For example, you can output an additional field with a drop-down list to the feedback form;
  • Result title — a text header that will be shown to a client after sending a submitted form. If this field is left empty, the text «Successfully sent!» will be displayed by default;
  • Result text — a text that will be shown to a client after sending a submitted form. If this field is left empty, the text «Your message has been successfully sent! Our specialists will contact you» will be displayed by default.

«Chat» block

Setting up chat with support:

  • Sound — a new message sound from an agent in a widget. If you want messages to come without sound, choose «not selected». Or choose one of five sounds after listening to them. If necessary, a client can mute sound in a widget;
  • Replace operator real name with — replace operator and bot names with one name;
  • Do not ask for an e-mail — tick the checkbox to avoid requesting the customer's mail before starting the chat. Remember that in this case you will not be able to automatically identify the client in the system and view the history of his requests;
  • Greeting — a message that the client will receive from you as soon as he starts chatting. The text can be divided into paragraphs using Enter or the <br/> tag — it needs to be inserted into the line between paragraphs;
  • Reaction — tick the checkbox below to send the text to the client («Reaction text»), if he writes «hello», «hello», «good afternoon». These words can be edited, i. e. added on request. Write to our suppor;
  • Reaction text;
  • Button text color in messages — set up the buttons in the widget to automate correspondence and set the color of the button text in this field;
  • Button background color in messages.

«Setting items» block

To make the icon appear in the widget, click the «Add» button, and set the values in any order. You can change the order of the typed items by drag-n-drop.Fill in the form opposite the desired item:
  • Tooltip — pop-up help. If the field is not filled, the tooltip is not displayed;
  • Picture — view of your button. Hover over the default icon, press «plus», and add your picture (size not exceeding 20 Mb, 48х48 px);
  • Link or list item for the following values:
    • Support centerif you have more than one knowledge base in your account, select the one you want to display in this particular widget. By default, the first knowledge base in the list is selected. The knowledge base will always be located at the top of the list in the widget, regardless of its location when you configure it;
    • VKontaktepage/group id;
    • Facebook — a link to the Facebook messenger dialogue with your company;
    • Vibera link to the public (viber://chat?number=%2B) or a phone number;
    • Telegramlink to a bot or account;
    • Odnoklassniki — a link to the group dialogue;
    • Instagram — profile link;
    • WhatsApp — a phone number without spaces and extra symbols (pluses, hyphens, brackets), only numbers;
    • Skype — chat link;
    • Link — outside link.

Add chat, messengers, social networks through the specified parameters, and use a new field «Link» to add necessary channels for your company through an outside link.

Important! The total number of icons in the widget is limited to 10.

Including the messenger in the widget does not integrate it with the Usedesk. Use the instructions to connect the messengers.

Our test widget

We have got a page with a test widget —
On this page you can see, how a widget, forms in a widget chat and buttons work.
Two triggers are set up in the widget: one sends a form when clicked the button, the other – sends a text. This is how they are set up:
The trigger with a text

The trigger with a form

User identification

If you allow customers to write to your widget without identifying them, they will not be recognized by the system. For some, the option without customer identification is suitable, but it has several advantages. For example:
  • agents will be able to address the client by name;
  • the client will be able to reply to the mail;
  • you will be able to collect the customer base using the widget.
There are several ways to identify a user:

1) Request mail before starting the chat. In the widget channel settings in the «Chat» block there is an item «Do not ask for an e-mail».

Turn it off so that before the conversation starts, the widget asks the client for mail and thus identifies him.

2) Feedback form. Use the feedback form together with the chat or separately.

When the feedback form is enabled, the widget will request a name and e-mail by default.

3) Auto-identification using the API. If users on your site have personal accounts, you can configure the transfer of data from your site to Usedesk via the API. Then users will not have to fill in personal data when using the widget and they will always be identified — no «unidentified elephants» or «rabbits» :)

This works using the useridentify parameter — read more in our API documentation at the link.

Buttons for direct contact

You can add buttons to the widget for direct contact with you, so that when you click on it, the client can write to you by mail or call.
To set up a button with which the client can write to you by mail, add the «Link» item in the «Set the items» block, and in the «Link» window, write . Instead of specify the email address to which customers will write to you.

To set up a button with which the client can call you, add the «Link» item in the «Set the items» section, and in the «Link» window, enter tel:+74477577755444. Instead of +74477577755444, specify the phone number to which customers will call you.


  • The maximum size of the files sent in the feedback form is 15 MB;
  • The maximum size of files sent in the chat is 50 MB;
  • The history of correspondence in the chat with the client identified by the API is saved;
  • The chat history of an unidentified client is saved until the browser cache is updated.


If an error occurs while sending a message, the system will display a notification «Failed to send a message. Please e-mail us at» in the upper right corner.
An error will only be visible when sending from the ticket interface.
Our support will advise you what to do.