After the administrator completesinitial configuration of the components in Web Widget (Classic)from the Admin Center and works with their developer toadd Web Widget (Classic) to their website, they can work with their developer to further customize the Web Widget (Classic), if desired.
This article is an overview for administrators about what advanced customizations are possible with the Web Widget (Classic). This article is meant to answer the question,"what else can I do with my Web Widget (Classic)?"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, seethe developer documentation for the Web Widget (Classic) APIinstead.
This article discusses these topics and widget customizations:
- Web部件(经典)定制计划
- Navigating Web Widget (Classic) API documentation
- Displaying the widget in a different language
- Prefill forms with user contact information
- Disabling ticket attachments
- Re-positioning the launcher
- 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 (Classic)
- Advanced configuration of Chat in the Web Widget (Classic)
- Offering end users multiple contact options
- Formatting code for multiple Web Widget (Classic) elements
For information about adding the Web Widget (Classic) to your site, seeUsing Web Widget (Classic) to embed customer service in your website.
For a complete list of Web Widget (Classic) documentation, seeWeb Widget (Classic) resources.
Web部件(经典)定制计划
Most Support administrators aren’t web developers and work with someone else to implement customizations to the Web Widget (Classic). They don’t customize the Web Widget (Classic) 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 (Classic) 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 (Classic), 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 (Classic) 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.
- 克雷亚会见关键利益相关者在你们公司te a list of requirements for your Web Widget (Classic). What colors do want to use? How do you want the Web Widget (Classic) 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 (Classic) by modifying the HTML of your website.
Navigating the Web Widget (Classic) API documentation
Here’s some important information to help developers navigate the Web Widget (Classic) API documentation on the Zendesk developer site.
Updated, organized developer docs and API syntax—The Web Widget (Classic) API syntax has changed, and we’ve also reorganized the Web Widget (Classic) 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, seethe developer documentation for the Web Widget (Classic) API.
New Chat APIs—For information about how the old Chat (Zopim) APIs map to the Web Widget (Classic) APIs, seeMigrating from the Chat Widget syntax to the unified Web Widget (Classic) syntax.
Displaying the widget in a different language
By default, the Web Widget (Classic) 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 todefor 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 (Classic) supports a subset ofZendesk's supported languages. If the end user's browser language is not supported by the Web Widget (Classic), 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.
你可以customize the widget so that it always appears in a specific language using thesetLocalecommand. 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 thesetLocalecommand.
Prefill forms with user contact information
你可以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 theidentifyandprefillsettings.
你可以also set user information to be read-only using theprefillsetting, 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 theidentifyandprefillsettings.
Disabling ticket attachments
If you have enabled attachments for your tickets, users can attach files to tickets submitted from the Web Widget (Classic), by default. However, you can disable this option, if needed.
For more information, see the developer documentation for theattachmentssetting of thecontactFormobject.
Re-positioning the launcher
The default position for the Web Widget (Classic) is the bottom-right of the browser; when a user clicks on the Web Widget (Classic) launcher, it opens by expanding upward.
你可以select a location for the Web Widget (Classic) 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 thepositionsetting to position the Web Widget (Classic) in the top-left, top-right, bottom-left, or bottom-right of the page.
For more information, see the developer documentation about thepositionsetting.
Offsetting widget placement
你可以use theoffsetsetting to reposition the Web Widget (Classic) on your desktop or mobile devices. Use the initialpositionsetting as the point of reference, and then use theoffsetsetting to move the Web Widget (Classic) horizontally, vertically, or both from that position (in pixels).
For more information, see the developer documentation for theoffsetsetting.
Customizing the color of the widget elements
你可以specify an overall 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) from the Web Widget (Classic) administration page (seeConfiguring components in Web Widget (Classic)).
However, if you want to customize specific elements, you need to use thecolorsetting. You can choose a unique color for each of these Web Widget (Classic) components:
- Launcher
- Button
- Button text
- Results list
- Header
- Article links
For accessibility purposes, the Web Widget (Classic) automatically adjusts colors using an algorithm to guarantee a minimum contrast ratio as specified by theWCAG guidelines.
For more information about customizing the color of Web Widget (Classic) elements, see the developer documentation for thecolorsetting.
Changing visible ordering in the widget
Suppressing widget features on specific pages
你可以enable the Contact Form, Chat, Talk, and help center in the Web Widget (Classic) and then use thesuppresssetting to change the features offered on particular pages of your site to suit your needs.
- 帮助中心挠度在一些页面吗
- 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 thesuppresssetting.
Customizing widget text
你可以change the text of the Web Widget (Classic) components in the table below, and you can also customize thehelp 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,SupportorFeedback, defined on the Web Widget (Classic) 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 messageorContact usdefined on the Web Widget (Classic) 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 messageorContact usdefined on the Web Widget (Classic) 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, orFeedbackdefined on the Web Widget (Classic) Admin page |
You use thetranslationsobject to change some of the default text displayed in the Web Widget (Classic). Translations are grouped by feature—for example, Launcher, help center, and Contact Form.
你可以explore a list of potential language codes inLanguage 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, seeDisplaying your widget in a different language.
Adding a subject line to the contact form
With thesubjectsetting on thecontactFormobject, you can set the Web Widget (Classic) 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 thesubjectsetting on thecontactFormobject.
Hiding the "View Original Article" button
TheView Original Articlebutton bridges the article in the Web Widget (Classic) and the article in the help center itself. You can hide this button by using thehelpCenterobject, and setting theoriginalArticleButtonproperty tofalse.
For more information, see the developer documentation for theoriginalArticleButtonsetting for thehelpCenterobject.
Limiting search results
With thefiltersetting on thehelpCenterobject, you can limit the results of searches performed from the Web Widget (Classic) to articles based on category, section, and labels. For more information, see the developer documentation for thefiltersetting.
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:
To limit search to a specific category:
To limit search to content in multiple categories:
To limit search to content with a specific label:
To limit search to content in a specific category and with specific labels:
Customizing the help center search placeholder text
The default placeholder text in the help center search box isHow can we help?你可以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 thesearchPlaceholdersetting.
IfContextual Help is enabled, you can also configure the Web Widget (Classic) to open to recommended articles, making it easier for your customers toself-serve. For more information, see the developer documentation for thesetSuggestionscommand for thehelpCenterobject.
Advanced configuration of Talk in the Web Widget (Classic)
您可以创建多个配置定义how Talk behaves in the Web Widget (Classic). With each configuration you can customize call routing and display options for Talk in the Web Widget (Classic), based on your needs and preferences.
The agent group that you want Web Widget (Classic) callback requests to be routed to
The priority of Web Widget (Classic) callback requests
Display Request a callback, Call us, or both of these options in the Web Widget (Classic)
Display an estimated wait time in the Web Widget (Classic)
If you have only created a single configuration of Talk in the Web Widget (Classic), this will automatically be the default configuration that displays in the Web Widget (Classic) whenever Talk is available.
If you have created multiple configurations of Talk in the Web Widget (Classic), you can use the Talk nickname setting to target the desired configuration.
For more information, see the developer documentation for thetalkobject, thenicknamesetting, andConfiguring Zendesk Talk settings for the Web Widget (Classic).
Advanced configuration of Chat in the Web Widget (Classic)
If you are using thelive chat in the Web Widget (Classic), you can offer Zendesk Chat functions in the Web Widget (Classic) 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 thechatobject.
For information about how the old Chat (Zopim) APIs map to the Web Widget (Classic) APIs, seeMigrating from the Chat widget syntax to the unified Web Widget syntax.
Offering end users multiple contact options
你可以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 (Classic), 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 thecontactOptionssetting.
Offering contact options with Chat
If Chat is configured for the 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 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 (Classic), 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 (Classic) 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.
62 Comments
I've been looking through documentation, but I have yet to find a way to suppress or change the "Top Results" text above the article titles. Did I overlook this, or does anyone have ideas? Thanks!
Hi Mark,
Unfortunately, it isn't possible to customise the 'Top results' string today. I'll log this as a feature request on our side for future consideration. Out of interest, what were you hoping to change this string to?
Thanks,
- Miranda.
谢谢你的快速反应,米兰达。我们甲型肝炎e been experimenting with ways to provide shorter answers to questions . . . so short that the title IS the answer. If we can constrain the list of returned articles down to 1, and either suppress "Top results" or just relabel it as "Answer", then it feels more like a direct answer to their question rather than a list of search results.
I'd welcome any guidance you have (including if you think this approach is not advisable).
I was in the process of writing up how to do exactly this.
Tip: Hide top suggestions on Web Widget
Let me know if you have any issues.
Great to hear, Alejandro!@...Sorry, but when I click your link it says "oops, you're not authorized to access this page" even though I'm logged in. Thanks!
Not sure what is going on there but here is the GitHub linkhttps://github.com/Ajhad1/Zendesk-Customizations/tree/main/Web-Widget/Hide-Top-Suggestions-Title
Perfect - much appreciated!
Hi, does anyone know if we can edit this text (image attached)?
Hello Mark,
Thanks for reaching out. Unfortunately, the ability to edit this is outside of Zendesk's native features. With that said this could be changed through custom code.
Thanks @kharlo! I appreciate your quick feedback and note that at least we could accomplish via custom code.
How to add specific colour to header title ?
It isn't currently possible to change the font colour of the header title. Only the background colour of the header can be customised at this stage. I'll log this as a feature request and we'll consider implementing it in the future.
Thanks,
- Miranda.
Based on the theme colour selected, we automatically choose whether a font colour of black or white is more appropriate based on the contrast ratio (in order to meet Accessibility standards).
- Miranda.
How to set by default one value to product dropdown.
Hey,
It can be done like so:
With 123456 the ID of the custom field and value the chooses option (if it's dynamic content use the underlying tag)
See also:
https://developer.zendesk.com/embeddables/docs/widget/settings#fields
For more customisation options try outhttps://widget.guide/demo/
Hello,
I'm looking to change two things that don't make sense to me on the Web Widget.
1 / When the Web Widget is displayed in full screen on mobile,I think it would be better to change this icon. More understandable.
2 / Also on mobile, I would like to add an "OK" or "Search" button, something like that, in the search bar. Few people are familiar with having to press the "Return" key on their smartphone keypad to validate a form. When I watch my visitors sessions with HotJar, I have approximately20%of people typing their search but failing to validate the form ...
Guess it is not possible to achieve this with custom code? Don't you think these are good ideas?
Thanks.
Hey Thibaut,
I double checked with one of our web widget experts and it doesn't look like there's a way to accomplish what you're looking for at this time.
I'd recommend cross-posting this in ourFeedback - Ticketing System (Support)topic and I'll be sure to share your thoughts with our Product Managers.
Thanks for taking the time to share this with us!
Hello Brett,
That's what I thought, unfortunately.
I just created a new topic.
Thank you.
Hi,
We use the same chat account for our Zendesk Knowledge Base and an external website. Is there a way to hide a chat field for our chat widget for just the external website?
Thank you,
Laura
Hi Laura,
I think the shared code snippet in this article, add to your external website script file and customize by the instructions:
https://support.zendesk.com/hc/en-us/articles/115010352968
Also this one:
https://support.zendesk.com/hc/en-us/articles/115009692388-Configuring-components-in-the-Web-Widget
你可以try once.
Thank You
Hello!
I've got a question regarding customizing either the (1) message bubble color or (2) the "Get in touch" button styling.
I've consulted theSettings Reference for the Web Widget (classic), which has given me a wonderful starting point, butI was wondering if either of the 2 elements above are targetable objects via the JS in that Settings Reference.
They currently both are taking their values from theTheme Colorsetting, which is really a problem as one has near-black text on it, and the other is overlaid on top of the widget's BG color (white). Whatever algorithm the widget uses to adjust colors does not appear to be active...Is there a way to force the accessibility color algorithm?
If not, finding a color that will be accessible in both circumstances is quite the challenge, so I'd like to be able to control one or both individually, as well as potentially the hover styling for the "Get in touch" button.
Thanks for your time.
Hi !
Is there a setting that prevents the selected article from being previewed in the widget, opening the article in a new page instead?
Hi Jais!
Thanks for your question! Unfortunately, there isn't a setting available to view help articles within a browser window, instead of the widget itself. I'll lodge this feedback on our side and we'll consider it in the future.
Have you considered transitioning across to ourmessaging experience? By default, within messaging, help articles are viewed within a browser (not within the widget itself).
Thanks,
- Miranda.
Dear Miranda,
谢谢你的回答。我没有机会to try the messaging experience yet, because it requires Agent Workspace, which I just disabled because I wasn't satisfyied by the poor Knowledge Base interaction (article suggestion is less good than with regular Knowledge Capture App, plus there's no integration of the nice features offered by KCapture such as flag, the stats of deflection, etc.).
I'll think about it and see if I shall reenable it.
Thanks!
HiTulasi
Also here:
Maria
Hi Mordechai Hammer,
Apologies for the delay in my reply. Appreciate your feedback.
There isn't a way to do this right now but agree with your feedback. I'll log this on our side for future consideration. We know this is an area that we need to improve and hope to dedicate some time to perfecting the colour matching algorithm in 2022.
Thanks! I'll log for future consideration as well.
- Miranda.
Hi Mordechai Hammer,
Apologies for the delay in my reply. Appreciate your feedback.
There isn't a way to do this right now but agree with your feedback. I'll log this on our side for future consideration. We know this is an area that we need to improve and hope to dedicate some time to perfecting the colour matching algorithm in 2022.
Thanks! I'll log for future consideration as well.
- Miranda.
Hi,
我们甲型肝炎e a customer that has a fixed footer , and wants the chat icon within a button format... is there a HTML code that I can try in order to make this happen ?
Hi Ntsako,
This can be accomplished by first hiding the widget on the page and then showing it using the widget's Javascript APIs once the custom button is clicked. We demonstrate this in more detail inQuickstart – Creating a launcher for the Web Widget (Classic).
Thanks,
When using the filter, if I filter based on label is it an 'AND' filter or 'OR' filter. Meaning, if I include labels: Label1 and Label2. Do the results limit to only articles that have both Label1 and Label2, or limit to any articles that have either Label1 or Label2.
Pleasesign into leave a comment.