After the administrator completes initial configuration of the components in the Web Widget from the Zendesk Support interface and works with their developer to add the Web Widget to their website, they can work with their developer to further customize the Web Widget, if desired.
This article is an overview for administrators about what advanced customizations are possible with the Web Widget. This article is meant to answer the question, "what else can I do with my Web Widget?" It explains the customization process for administrators, and also points to developer documentation that web developers need in order to do the work.
If you’re a web developer (or an administrator who is comfortable doing website development on your own) and are looking for complete documentation about the API settings and commands described in this article, or additional code samples, see the developer documentation for the Web Widget API instead.
This article discusses these topics and widget customizations:
- Planning for Web Widget customizations
- Navigating Web Widget API documentation
- Displaying the widget in a different language
- Prefill forms with user contact information
- Disabling ticket attachments
- Re-positioning the widget
- Offsetting the widget placement
- Customizing the color of the widget elements
- Changing visible ordering in the widget
- Suppressing features on specific pages
- Customizing widget text
- Adding a subject line to the contact form
- Hiding the "View Original Article" button
- Limiting search results
- Customizing the Help Center search placeholder text
- Advanced configuration of Talk in the Web Widget
- Advanced configuration of Chat in the Web Widget
- Offering end-users multiple contact options
- Formatting code for multiple widget elements
For information about adding the Web Widget to your site, see Using Web Widget to embed customer service in your website.
For a complete list of Web Widget documentation, see Web Widget resources.
Planning for Web Widget customizations
Most Support administrators aren’t web developers and work with someone else to implement customizations to the Web Widget. They don’t customize the Web Widget and websites on their own. They work with a web developer at their company, or an outside developer that they use on a contract basis to implement the changes.
The web developer is the person who does the customization work, and they do it by adding some code (the Web Widget API) to the HTML of the website. However, the administrator still has a role to play in the work. They need to understand what customizations are possible for the Web Widget, and tell the web developer what they want.
Some administrators have experience with HTML and choose to do the customization work themselves, acting as their own developer, and that's fine. Either way, customizing the Web Widget is actually a process for the administrator that requires some planning and involves these steps:
- Review the information in this article to understand what advanced customizations are possible.
- Meet with key stakeholders at your company to create a list of requirements for your Web Widget. What colors do want to use? How do you want the Web Widget to behave?
- Prepare a list of the customizations you want. Be as specific as possible and include links to API documentation that your web developer can reference.
- Give the list to your web developer, who will customize the Web Widget by modifying the HTML of your website.
Navigating the Web Widget API documentation
Here’s some important information to help developers navigate the Web Widget API documentation on the Zendesk developer site.
Updated, organized developer docs and API syntax— The Web Widget API syntax has changed, and we’ve also reorganized the Web Widget API developer documentation to make it easier to find the command or setting you’re looking for. The documentation is now organized by product channel (Help Center, Tickets, Chat and Talk) or by core settings and commands. For more information, see the developer documentation for the Web Widget API.
New Chat APIs—For information about how the old Chat (Zopim) APIs map to the new Web Widget APIs, see Migrating from the Chat Widget syntax to the unified Web Widget syntax.
Displaying the widget in a different language
By default, the Web Widget embedded in a website displays text in the end user’s language, based on the language of their browser. For example, if the end user's browser language is set to de for German, the widget will appear in German for that user. If the widget is embedded in a Help Center, it displays text based on the Help Center language setting.
The Web Widget supports a subset of Zendesk's supported languages. If the end-user's browser language is not supported by the Web Widget, the widget defaults to English. If the widget is unable to obtain the language from the end-user’s browser, the widget defaults to the language specified in Zendesk Support.
You can customize the widget so that it always appears in a specific language using the setLocale command. This command sets the language for only the widget and doesn't override your host page’s language.
For more information, see the developer documentation for the setLocale command.
Prefill forms with user contact information
You can save visitors to your site a few seconds and some annoyance or frustration by prefilling their name, email address, and phone number into 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 to be read-only using the prefill setting, which is nice because you can avoid having duplicate user accounts in Support for the same person.
For more information, see the developer documentation for the identify and prefill settings.
Disabling ticket attachments
If you have enabled attachments for your tickets, users can attach files to tickets submitted from the Web Widget, by default. However, you can disable this option, if needed.
For more information, see the developer documentation for the attachments setting of the contactForm object.
Re-positioning the widget
The default position for the Web Widget is the bottom-right of the browser; when a user clicks on the Web Widget, it opens by expanding upward.
You can select a location for the Web Widget that varies from page to page (placing it on the left or right side of the page, or moving it to the top of the page where it expands downward when clicked). Use the position setting to position the Web Widget in the top-left, top-right, bottom-left, or bottom-right of the page.
For more information, see the developer documentation about the position setting.
Offsetting the widget placement
You can use the offset setting to reposition the Web Widget on your desktop or mobile devices. Use the initial position setting as the point of reference, and then use the offset setting to move the Web Widget horizontally, vertically, or both from that position (in pixels).
For more information, see the developer documentation for the offset setting.
Customizing the color of the widget elements
You can specify an overall color scheme for the Web Widget (theme color) and a custom color for the text in the launcher, contact button, and header (theme text color) from the Web Widget administration page (see Configuring components in the Web Widget).
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:
- Launcher
- Button
- Button text
- Results list
- Header
- Article links
For accessibility purposes, the Web Widget automatically adjusts colors using an algorithm to guarantee a minimum contrast ratio as specified by the WCAG guidelines.
For more information about customizing the color of Web Widget elements, see the developer documentation for the color setting.
Changing visible ordering in the widget
Suppressing widget features on specific pages
You can enable the Contact Form, Chat, Talk, and Help Center in the Web Widget and then use the suppress setting to change the features offered on particular pages of your site to suit your needs.
- Have Help Center deflection on some pages
- Have Chat or the Contact Form without deflection on other pages
- Offer tiered service levels to signed in and identified users
For more information, see the developer documentation for the suppress setting.
Customizing widget text
You can change the text of the Web Widget components in the table below, and you can also customize the Help Center search placeholder text.
Component | Details |
---|---|
![]() |
Object: launcher Setting: chatLabel Description: Text on the launcher button when Chat is enabled and Help Center is not onDefault text: Chat |
![]() |
Object: launcher Setting: label Description: Text on the launcher button Default text: Help, Support or Feedback (defined on the Web Widget Admin page) |
![]() |
Object: helpCenter Setting: title Description: The title of the Help Center page Default text: Help |
![]() |
Object: contactForm Setting: title Description: Title of the contact formDefault text: Leave us a message or Contact us (defined on the Web Widget Admin page) |
![]() |
Object: helpCenter Setting: messageButton Description: Text on the button in the Help Center form that loads the Contact form (~20 character limit) Default text: Leave us a message or Contact us (defined on the Web Widget Admin page) |
![]() |
Object: helpCenter Setting: chatButton Description: Text on the button shown in the Help Center form that loads the Chat (~20 character limit)Default text: Help, Support, or Feedback (defined on the Web Widget Admin page) |
You use the translations object to change some of the default text displayed in the Web Widget. Translations are grouped by feature—for example, Launcher, Help Center, and Contact Form.
You can explore a list of potential language codes in Language codes for Zendesk supported languages.
The locale translations are triggered by the end user's browser language. You can also force the widget to always appear in a specific language and override the end-user's browser language setting. For more information, see Displaying your widget in a different language.
Adding a subject line to the contact form
With the subject setting on the contactForm object, you can set the Web Widget to include a subject field in the default contact form.
The default contact form is designed to promote engagement and offer a streamlined user experience when completing the contact form. While the default contact form does not include a subject line, you may want to add one to enhance the support experience for some customers.
For more information, see the developer documentation for the subject setting on the contactForm object.
Hiding the "View Original Article" button
The View Original Article button bridges the article in the Web Widget and the article in the Help Center itself. You can hide this button by using the helpCenter object, and setting the originalArticleButton property to false.
For more information, see the developer documentation for the originalArticleButton setting for the helpCenter object.
Limiting search results
With the filter setting on the helpCenter object, you can limit the results of searches performed from the Web Widget to articles based on category, section, and labels. For more information, see the developer documentation for the filter setting.
Scroll down for some additional examples that are not included in the developer docs that illustrate some of the ways you can limit search results.
To limit search to a specific section:
<script type="text/JavaScript">
window.zESettings = {
webWidget: {
helpCenter: {
filter: {
section: '200154474-Announcements'
}
}
}
};
</script>
To limit search to a specific category:
<script type="text/JavaScript">
window.zESettings = {
webWidget: {
helpCenter: {
filter: {
category: '200053794-General'
}
}
}
};
</script>
To limit search to content in multiple categories:
<script type="text/JavaScript">
window.zESettings = {
webWidget: {
helpCenter: {
filter: {
category: '115000669485,201742209'
}
}
}
};
</script>
To limit search to content with a specific label:
<script type="text/JavaScript">
window.zESettings = {
webWidget: {
helpCenter: {
filter: {
label_names: 'orders'
}
}
}
};
</script>
To limit search to content in a specific category and with specific labels:
<script type="text/JavaScript">
window.zESettings = {
webWidget: {
helpCenter: {
filter: {
category: '200053794-General',
label_names: 'Label One,Label Two,Label Three'
}
}
}
};
</script>
Customizing the Help Center search placeholder text
The default placeholder text in the Help Center search box is How can we help? You can customize this text so that it matches the user’s language, or so that specific text appears in certain languages. For more information, see the developer documentation for the searchPlaceholder setting.

If Contextual Help is enabled, you can also configure the Web Widget to open to recommended articles, making it easier for your customers to self-serve. For more information, see the developer documentation for the setSuggestions command for the helpCenter object.
Advanced configuration of Talk in the Web Widget
You can create multiple configurations that define how Talk behaves in the Web Widget. With each configuration you can customize call routing and display options for Talk in the Web Widget, based on your needs and preferences.
-
The agent group that you want Web Widget callback requests to be routed to
-
The priority of Web Widget callback requests
-
Display Request a callback, Call us, or both of these options in the Web Widget
-
Display an estimated wait time in the Web Widget
If you have only created a single configuration of Talk in the Web Widget, this will automatically be the default configuration that displays in the Web Widget whenever Talk is available.
If you have created multiple configurations of Talk in the Web Widget, you can use the Talk nickname setting to target the desired configuration.
For more information, see the developer documentation for the talk object, the nickname setting, and Configuring Zendesk Talk settings for the Web Widget.
Advanced configuration of Chat in the Web Widget
If you are using the Web Widget integrated Chat experience, you can offer Zendesk Chat functions in the Web Widget so that visitors to your website can chat with agents, and send and receive files that might help with their problem. Agents can also send proactive messages to visitors, to see if they want or need any help.
For more information, see the developer documentation for the chat object.
For information about how the old Chat (Zopim) APIs map to the new Web Widget APIs, see Migrating from the Chat Widget syntax to the unified Web Widget syntax.
Offering end users multiple contact options
You can allow end users to choose a contact option. You may want to customize your website so that some pages allow end users to make a choice and others don’t. The exact behavior depends on whether Chat or Talk is configured for the Web Widget, and whether a chat agent is online. You can customize the default text of contact options, if needed.
Here's a list of the default text:
Contact option | Default text |
---|---|
Contact button | Contact us |
Chat label (with agent online) | Live chat |
Chat label (with agent offline | Chat is unavailable |
Contact form label | Leave us a message |
For more information, see the developer documentation for the contactOptions setting.
Offering contact options with Chat
If Chat is configured for the Web Widget, 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 completing a contact form, even if a chat agent is available. If a chat agent is available when the user clicks the launcher, but the agent signs off before the chat begins, the end users may see a message indicating that the agent is not available.
It's a known issue that when end users choose to chat, they cannot use the back button to return to the other contact options. To do so, they need to completely end the chat or refresh the page.
Offering contact options with Talk
If Talk and other contact options are enabled in the Web Widget, and agents are online, contact options are automatically enabled.
Formatting code for multiple widget components
Items that are specific to the Contact Form, Help Center, and Zendesk Chat are nested under those headings (contactForm, helpCenter and chat) in the HTML of your site, while global items are included separately.
- The position of the Web Widget on the screen has been changed using the offset setting. Offset is a global item, which is why it has its own entry.
- Help Center search—doesn’t include the View Original Article button. The title “Search for help” for English-language users, and “Have your say” for all other languages.
- Chat is disabled.
- The contact form title is “Message us” in English and “Contact us” in 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>
247 Comments
@heather: I see the Widget fine in my tests in Safari; I've created a support ticket for you.
It's great to be able to use these customizable options! Our help center is moxiworks.zendesk.com and I'm trying to get the Help button to align with the right edge of the rest of our elements and stay there no matter how the browser is resized. Linked are a couple screenshots of what we want it to look like. You can see what it actually looks like on the live site now.
Full Screen
Resized
Any tips?
@joshua. We currently do not have a way to enable you to fully anchor the launcher. What you could do though is build your own button within the site design that could serve as a custom launcher and then you could use zE.activate to have it open the Widget.
Thanks, Erica. I played around with that a little bit on our site and it seems easy enough but how do I enable that without displaying the widget? Also, I'm not sure how we'd get the button to open the menu in a different location. Example: I'd like the customer to click on it and have the widget open right where the button is.
@joshua You'd use zE.activate in conjunction with zE.hide; you could use the offset and position settings as well. It won't remain perfectly oriented through zoom changes but I think if you play around with it you should be able to get something that works well.
Looks like the web widget's options to customize have improved big time for the last 2 years. We are evaluating finally using the widget. That said, is there an option to customize the size of the expanded widget?
Re-positioning and offseting is good but what about resizing?
Hi George!
Thanks for the feedback!
Erica previously noted this, so rather than paraphrasing her words, I'll share what she had said:
"No, I'm afraid that there is no sizing configurations currently available for the Widget. But I'd be eager to learn more about your design needs. The Widget is optimized for mobile devices so should appear well on mobile devices, so I'd be interested in learning more about what you're seeing."
How do I get the category id to which the section/article belongs when I am on that page? For example, if I am on the Section or Article page and I want to filter the widget's search scope to the Category to which it belongs. How can I access the category id?
I am trying to set the category filter via script on top of the Section/Article page template, but I can't access the category object.
What's the best way to do this? Thanks.
Hi Hoff Ho,
If you're looking for the Category ID, you should be able to find that by either navigating to that Category and then looking in the URL for that page:
Cheers,
Ben Goff
Thanks Ben, the problem is that I need to find the category when I am either viewing a Section or an Article. For example, from an URL such as ../sections/201416433-General-FAQs or ../articles/210618263-How-can-I-cancel-an-appointment-I-booked-online-, how can I programatically tell which Category it belongs to?
The Section object https://developer.zendesk.com/apps/docs/help-center-templates/objects#section-object does not have any properties to the parent Category. I can probably write some code to parse the breadcrumbs object and look for the Category name from there, but I am asking if there is a better way.
Hey Hoff Ho,
Unfortunately I'm not aware of a better way to surface that information, other than through the breadcrumbs, as you suggested. As you've pointed out, we unfortunately don't have another object or placeholder specific to Sections, to pull that information through.
Cheers,
Ben Goff
FYI I managed to get this to work. It's not the most elegant code but it works.
Append to JS
function getCatFromBC() {
// returns the Category Name from the breadcrumbs - snippet below
// <li title="Patient">
// <a href="/hc/en-us/categories/200431715-Patient">Patient</a>
// </li>
var CATS = '/categories/';
var QUOTE = '"';
var x = document.getElementsByClassName("breadcrumbs");
var y = x[0].innerHTML;
var z = y.search(CATS);
var cat = '';
if (z > -1) {
var a = y.slice(z + CATS.length);
var d = a.search(QUOTE);
if (d > -1) {
cat = a.slice(0, d);
}
}
return cat;
}
Put this in the Section or Article pages
<nav class="sub-nav clearfix category-breadcrumbs">
{{breadcrumbs}}
</nav>
<script type="text/JavaScript">
var catName = getCatFromBC();
window.zESettings = {
webWidget: {
helpCenter: {
filter: {
category: catName
}
}
}
};
</script>
BTW, this works better than the search box {{search scoped=true}} in the Header as that does not seem to work. I have read a few recent threads reporting this and I am also getting this. Not sure if it is a byproduct of introducing the web widget.
Help Center API endpoints for this are available to anonymous end users... could you do a call to the section endpoint based on the section ID and retrieve the parent category ID?
https://developer.zendesk.com/rest_api/docs/help_center/sections
Thanks for coming back and sharing what you figured out, Hoff!
Is there a way to change the colour of the Help Center search bar within the Widget? As per image below e.g. so the gray bar is navy and font is white.
My theme colour is navy blue, which looks great when the widget is closed, but this doesn't really fit.
Also, is there a way of turning auto complete on within the widget?
Hi @Dan, not currently but we are working on some new enhancements that might include a theme colored header. Can you tell me a bit more about your goals for autocomplete? There are a few types so I want to make sure I'm fully across what you're trying to achieve.
Is it possible to skip viewing the article contents within the Web Widget? For example, if someone clicks on one of the articles it would open a new window and take them directly to it. I would prefer this over showing the consents within the Web Widget itself.
@Erica - Thanks v interested to hear more about the new enhancements when ready. For the auto-complete, I'm hoping there's a way that a user can see suggested results 'on the fly' without having to hit enter/click search. e.g. if I type in the word 'cancel', articles which match this entry would be suggested to the user without them having.
Hope that makes sense.
Also a further question - is there a way to make the widget less obstructive in mobile? e.g. have it partially hidden on the bottom of the screen? I'm finding it is a little distracting from our main site content when on a smaller device.
Any plans to allow us to customize the "message sent" pop-up? I would like to use this as a thank you page and set expectations on when the customer should hear back from support. This is valuable real estate and a big check mark is a waste of space. thanks
I was wondering if there is a way to suppress the widget on a certain page of a website? For example we want the user to log in to our website first before they can then use the widget, so we want to suppress the widget on the logon page.
Hey Phil!
There isn't a setting for this so, if it's possible, it would require adding JS code to the widget. I'm sorry I can't be more help than that.
@phil to add to Jessie's comments, the individual articles also have a "View original article" button that will take them to that article in the Help Center. I'm eager to hear more about your use case and your preference to not display article content in the Widget.
@dan thanks for your additional feedback. I have received some other requests regarding the mobile launcher so we'll be seeing how we could add some greater flexibility. In the meantime, you could create a custom launcher within your site design that would activate the Widget. We don't have any specific plans for the autosearch, but have made a note of the request.
@shannon Thanks for writing. It's something we're thinking about broadly so I appreciate your use case.
@heather I think you have a few options. You could 1) remove the snippet from the login page or other pages where you don't want it to appear, or 2) Use the Suppress advanced customization to suppress all features, or 3) Develop some custom code that only displays the Web Widget to logged in users.
We need at our company web widgets into basque, but it isn't available. Would it be possible to help translating it?
I have the following piece of code which works perfectly in Chrome but not IE 11:
<script type="text/javaScript">window.zESettings = {webWidget: {authenticate: {jwt: <?php echo json_encode($wsstoken); ?>}, helpCenter: {suppress: false, filter: {category: '200322819-Practice'}}}};</script>
I have a valid $wsstoken, and the category '200322819-Practice' has restricted access hence the JWT required. The behaviour in IE as if the JWT authentication does not work. FYI I have also tested the filter of a category which does not have restricted access and that worked as expected.
Do you have any suggestion on how to get this to work in IE 11?
Hi Jon!
Basque translation is available through volunteer transators! You can try implementing it on your Guide using our Web Widget API
https://developer.zendesk.com/embeddables/docs/widget/api
Hope this helps!
@Diogo Maciel, could you tell me where must I look into to customize translations? Thank you!
Hi Hoff!
I see that you're already getting assistance with this in a ticket, so we'll be assisting you from there!
Is there a way to add a custom link to the widget? I would like to add a permanent link back to the Help Center website (at a particular category), but I can't see how to do this.
@hoff ho, not currently. You could add one to an article, however, and it would open.
@Erica Wass - Can you please clarify? Do you mean that it is possible:
1) To add an article link to the widget?
2) To add an external link to an article?
We would also like to add a Help Center article link to the widget, much as it is possible to do with the web ticket creation form described here:
https://support.zendesk.com/hc/en-us/articles/203661336-Customizing-custom-ticket-field-descriptions-with-HTML
Please sign in to leave a comment.