Advanced Web Widget Customization (Classic) – Barbara Demos

After the administrator completes the initial setup of the Web Widget (classic) components in the Admin Center and collaborates with the developer to add the Web Widget (classic) to the website, he can further customize the Web Widget (classic) if desired.

This article is an overview of advanced customizations available in Web Widget (classic) for administrators. The purpose of the article is to answer the question "What else can I do with my (classic) Web Widget?" It explains the customization process for administrators and also lists documentation that web developers need to consult.

If you are a web developer (or an administrator with development skills) and are looking for complete documentation on the API settings and commands described in the article, as well as other code samples, see the developer documentation for the Web API Widget (classic).

This article covers the following widget topics and customizations:

Web Widget Customization Planning (Classic)
Browsing the Web Widget API Documentation (Classic)
Displaying your widget in a different language
Filling in forms with user contact information
Disabling ticket attachments
Launcher repositioning
Widget position shift
Customizing the color of widget elements
Changing the order visible in the widget
Suppression of features on specific pages
Text customization in the widget
Inclusion of the subject line in the contact form
Hiding the "View Original Article" button
Limitation of search results
Customizing placeholder text in the help center search box
Advanced Talk Configuration in the Web Widget (Classic)
Advanced Chat Setup in Web Widget (Classic)
Offering multiple contact options for end users
Code Formatting of Various Web Widget Elements (Classic)

For information on how to add the Web Widget (classic) to your website, see Using the Web Widget (classic) to embed customer service on your website.

For a complete list of Web Widget (Classic) documentation, see Web Widget (Classic) Features.

Web Widget Customization Planning (Classic)

Many Support administrators are not web developers and work with someone else to implement the (classic) Web Widget customizations. They do not customize the (classic) Web Widget and websites themselves. They work with the company's or third-party web developer hired to implement the changes.

The web developer does the customization work, adding the code (Web Widget API (classic)) to the website's HTML. However, the administrator is still needed for the job. He needs to know what customizations are possible for the (classic) Web Widget and tell the web developer what he wants.

Some administrators are experienced with HTML and choose to do the customizations themselves, acting as developers. However, customizing the Web Widget (classic) is an administrator process that requires planning and involves the following steps:

Study the information in this article to learn about the advanced customizations available.
Meet with the company's key stakeholders to create a list of requirements for the (classic) Web Widget. What colors should be used? How should the Web Widget (classic) behave?
Prepare a list of desired customizations, being as specific as possible and including links to API documentation that the web developer can refer to.
Pass the list to the developer who will customize the Web Widget (classic) by modifying the website's HTML.
Browsing the Web Widget API Documentation (Classic)

We have some important information to help developers navigate the Web Widget API (classic) documentation on the Zendesk developer site.

Updated and Organized Developer Documentation and API Syntax — Web Widget (Classic) API syntax has changed, and we reorganized the Web Widget (Classic) API Developer Documentation to make it easier to find the desired command or configuration. Documentation is now organized by product channel (Help Center, Tickets, Chat and Talk) or by main commands and settings. For more information, see the developer documentation on the Web Widget API (classic).

New Chat APIs — For information on mapping the old Chat APIs (Zopim) to the Web Widget APIs (classic), see Migrating Chat Widget Syntax to Web Widget Unified Syntax (Classic).

Displaying your widget in a different language

By default, the (classic) Web Widget embedded in the website displays text in the end user's language, based on their browser language.

For example, if the end user's browser language is set to from to German, the widget will be displayed in German to the user. If the widget is embedded in the help center, it displays text based on the help center language setting.

The Web Widget (classic) supports a subset of languages supported by Zendesk. If the end user's browser language is not supported by the Web Widget (classic), the widget will be in English by default. If the widget cannot get the language of the end user's browser, the widget returns to the language specified in Zendesk Support by default.

You can customize the widget so that it is always displayed in a specific language using the setLocale command. This command sets the language for the widget only and does not override the language of your main page.

For more information, see the developer documentation on the setLocale command.

Filling in forms with user contact information

Save your website visitors time and avoid their annoyance and frustration by pre-filling customers' name, email and phone number in contact forms. This includes ticket forms, pre-chat forms, and Chat offline forms. Use the identify and prefill settings.

You can also set user information as read-only with the prefill setting. This is great as it avoids creating duplicate user accounts in Support.

For more information, see the developer documentation on the identify and prefill settings.

Disabling ticket attachments

If you allow attachments on tickets, users can attach files to tickets sent from the Web Widget (classic) by default. However, if you need to, you can disable this option.

For more information, see the developer documentation on configuring attachments of the contactForm object.

Launcher repositioning

The default position of the Web Widget (classic) is in the lower right corner of the browser. When a user clicks on the (classic) Web Widget launcher, it opens and expands to the top.

You can select a location for the Web Widget (classic) that varies by page (on the left or right of the page, or at the top, expanding downwards when opened). Use the position setting to place the Web Widget (classic) in the top left, top right, bottom left or bottom right corner of the page.

For more information, see the developer documentation on the position setting.

Widget position shift

You can use the offset setting to reposition the Web Widget (classic) on your computer or mobile devices. Use the starting position setting as a reference point and use the offset setting to move the (classic) Web Widget horizontally, vertically or both (in pixels).

For more information, see the developer documentation on setting offset.

Customizing the color of widget elements

You can specify a general color scheme for the Web Widget (classic) (theme color) and a custom color for the text in the launcher, contact button and header (theme text color) in the web admin page Widget (classic). See Configuring the components in the Web Widget (classic).

However, if you want to customize specific elements, you need to use the color setting. You can choose a unique color for each of these Web Widget components (classic):

launcher
Button
button text
list of results
Header
Links to articles

For better accessibility, the Web Widget (classic) automatically adjusts colors using an algorithm that guarantees a minimum contrast ratio, as specified in the WCAG guidelines.

For more information on customizing the colors of Web Widget elements (classic), see the developer documentation on the color setting.

Changing the order visible in the widget

You can use the zIndex configuration, one of the main ones of the Web Widget (classic), to set a new value and change the display of the Web Widget (classic) compared to other elements in the same location on the site.

For more information, see the developer documentation on zIndex configuration.

Suppression of widget features on specific pages

It is possible to activate the Contact Form, Chat, Talk and Help Center on the Web Widget (classic) administration page and use the suppress setting to change the features offered on certain pages of your website to better meet your needs .

For example, you can use suppress to:
Increase ticket deflection with help center on some pages
Offer Chat or Contact Form without deflection on other pages
Offer different levels of service to users connected or identified

For more information, see the developer documentation on the suppress configuration.

Text customization in the widget

You can also change the text of the Web Widget components (classic) in the table below and customize the placeholder text in the help center search.

Component Details

Object: launcher

Configuration: chatLabel

Description: text on launcher button when Chat is enabled and Help Center is not enabled

Default text: Chat

Object: launcher

Configuration: label

Description: text on launcher button

Default text: Help, Support or Feedback, as defined in the Web Widget admin page (classic)

Object: helpCenter

Configuration: title

Description: Help Center page title

Default text: Help

Object: contactForm

Configuration: title

Description: contact form title

Default text: Leave a message or Contact us, as defined in the Web Widget admin page (classic)

Object: helpCenter

Configuration: messageButton

Description: text in the help center form button that loads the contact form (approximately 20 characters limit)

Default text: Leave a message or Contact us, as defined in the Web Widget admin page (classic)

Object: helpCenter

Configuration: chatButton

Description: text in the button displayed on the help center form that loads the Chat (approximate limit of 20 characters)

Default text: Help, Support or Feedback, as defined in the Web Widget admin page (classic)

Use the translations object to change parts of the default text displayed in the Web Widget (classic). Translations are grouped by feature such as Launcher, Help Center or Contact Form.

Note: If you specify the wildcard character (*) for the language name, the string will apply to all languages.

See the list of commonly used locales at Language codes for languages supported by Zendesk.

Local language translations are enabled by the language of the end user's browser. You can also force the widget to always display in a specific language by overriding the end user's browser language setting. For more information, see Displaying your widget in a different language.

Inclusion of the subject line in the contact form

With the subject setting in the contactForm object, you can configure the Web Widget (classic) to include a subject field in the standard contact form.

The default contact form is designed to drive engagement and provide an elegant user experience when filling out the form. Although the standard contact form does not have a subject line, you can add it to improve the support experience for some customers.

For more information, see the developer documentation about setting subject in the contactForm object.

Hiding the "View Original Article" button

The button View the original article creates a bridge between the article in the Web Widget (classic) and in the help center. You can hide this button using the helpCenter object and set the originalArticleButton property to false.

For more information, see the developer documentation on setting the originalArticleButton helpCenter object.

Limitation of search results

With the filter setting on the helpCenter object, you can limit the results of searches performed on the Web Widget (classic) to articles based on categories, sections and labels. For more information, see the developer documentation on the filter configuration.

Scroll down to see examples that aren't included in the developer documentation and that illustrate some ways you can narrow your search results.

Note: To specify multiple sections, categories, or labels, use a comma to separate the values (no spaces before or after are required).

How to limit the search to a specific section:

How to limit the search to a specific category:

How to limit your search to content in multiple categories:

How to limit search to content with a specific label:

How to limit search to content in a specific category with specific labels:

By default, the placeholder text displayed in the help center search box says How can we help? You can customize this text to match the user's language or to have specific text displayed in some languages. For more information, see the developer documentation on the searchPlaceholder configuration.

If Contextual Help is enabled, you can configure the Web Widget (classic) to open recommended articles, facilitating self-service for customers. For more information, see the developer documentation on the setSuggestions command of the helpCenter object.

Advanced Talk Configuration in the Web Widget (Classic)

You can create various settings that define how Talk behaves in the Web Widget (classic). With each setting, you can customize call forwarding and display options for Talk in Web Widget (classic) based on your needs and preferences.

The main attributes that you can customize in each configuration are:

Agent group that you want callback requests from the Web Widget (classic) to be forwarded to

Web Widget callback requests priority (classic)

Display of Request a Callback, Call Us, or both options in the Web Widget (classic)

Display of estimated wait time in Web Widget (classic)

If you have created a single Talk configuration in the Web Widget (classic), this will be the default configuration displayed in the Web Widget (classic) whenever Talk is available.

If you have created multiple Talk configurations in the Web Widget (classic), you can use the Talk nickname definition to achieve the desired configuration.

Note: The nickname in the Talk settings API request must exactly match the nickname in your Talk setup, including spaces and capital letters.

For more information, see the developer documentation on the talk object, the nickname configuration, and the article Configuring Zendesk Talk Settings for the Web Widget (classic).

Advanced Chat Setup in Web Widget (Classic)

If you are using real-time chat in the Web Widget (classic), you can make Zendesk Chat functions available in the Web Widget (classic) so that your website visitors can chat with agents, or send and receive files that can help in solving the problem. Agents can also proactively message visitors to ask if they want or need help.

For more information, see the developer documentation about the chat object.

With the integrated chat widget and web experience, you can further customize the chat object with the following settings:
title
concierge
departments
prechatForm
offlineForm
notifications
tags
authenticate

For information on mapping the old Chat (Zopim) APIs to the Web Widget (classic) APIs, see Migrating Chat Widget Syntax to Web Widget Unified Syntax.

Offering multiple contact options for end users

You can allow end users to choose a contact option. You can also customize your website so that some pages allow end users to make a choice and others do not. The exact behavior depends on whether Chat or Talk is configured for Web Widget (classic) and whether the chat agent is online. If necessary, you can customize the default text for the contact options.

We list the default text:

Default text contact option
Contact button Contact us
Chat label (with online agent) Live chat
Chat label (with offline agent) Chat not available
Contact form label Leave a message

For more information, see the developer documentation on setting contactOptions.

Offering Chat Contact Options

If Chat is configured for Web Widget (classic), end users are automatically routed to a chat if a Chat agent is available. However, you can allow end users to choose between chatting with an agent or filling out a contact form, even if a Chat agent is available. If a Chat agent is available when the user clicks the launcher, but that agent leaves the chat before it starts, the user is you may see a message informing you that the agent is not available.

It's a known issue: when end users choose to chat, they cannot use the back button to choose other contact options. To do so, they need to end the chat completely or refresh the page.

Offering contact options with Talk

If Talk and other contact options are enabled in the Web Widget (classic) and agents are online, then the contact options will be enabled automatically.

Code formatting of various widget components
Note: this section is for educational purposes only. Zendesk does not support or guarantee the code. It also doesn't support third-party technologies like JavaScript, jQuery, or CSS. Post issues you find in the comments or search for a solution online.

Contact Form, Help Center and Zendesk Chat specific items are nested under these headers (contactForm, helpCenter and chat) in your site's HTML, while global items are included separately.

For example, the following customizations have been defined:
The position of the Web Widget (classic) on the screen has been changed using the “offset” setting. Offset is a global item, with its own entry.
Help Center Search — does not include the View Original Article button. The title “Search for help” for users whose language is English and “Have your say” for the other languages.
Chat is disabled.
The title of the contact form is “Message us” for English and “Contact us” for other languages.
The launcher button text is “Make a request” in English and “Get help” in other languages.
<script type="text/JavaScript">
window.zESettings = {
webWidget: {
offset: { horizontal: '400px', vertical: '400px' },
helpCenter: {
originalArticleButton: false,
title: {
'en-US': 'Search for help',
'*': 'Have your say'
}
},
chat: {
suppress: true
},
contactForm: {
title: {
'en-US': 'SMessage us',
'*': 'Contact us'
}
},
launcher: {
label: {
'en-US': 'Make a request',
'*': 'Get help'
}
}
}
};
</script>