This hands-on tutorial shows you how to embed the Web Widget on a web page, and configure some basic settings using Web Widget APIs.
Basic Web Widget configuration can be performed in the Admin section of Zendesk Support > Admin. However, the Web Widget APIs provide more extensive Web Widget customization.
The Web Widget APIs are client-side JavaScript APIs that can be used in your website. The Web Widget API lets you change properties of the Web Widget using settings or perform actions using commands. This quickstart shows you how to work with both settings and commands.
Though not necessary to work through this quickstart, a general understanding of HTML and JavaScript is recommended to use the Web Widget API in your organization's website. For more information, see HTML Introduction and JavaScript MDN.
This tutorial contains the following sections:
Related information:
Requirements
-
CodePen, a free online code editor. While this tutorial uses CodePen, you can use other code editors such as JSFiddle and JS Bin.
-
A Zendesk Support account or a trial account. You can request a sponsored test account that doesn't expire after 14 days like the trial account.
-
Supported web browsers for the Web Widget, as described in Using Web Widget to embed customer service in your website.
Creating a sample web page
In this section, you'll create a “Hello World” web page in CodePen, an online code editor.
To create a “Hello World!” web page
- In your web browser, go to https://codepen.io/pen/.
- In the top UI pane, click Change View, and select the left view option.
- In the HTML editor on the top right side, click the dropdown menu, and select Maximize HTML Editor.
- Copy and paste the following HTML code into the HTML editor.
<!DOCTYPE html> <html lang="en"> <head> <title>Hello, World!</title> </head> <body> <p>Hello, World!</p> </body> </html>
The web page is displayed in the window on the right side.

Adding the Web Widget on your web page
To add the Web Widget on your web page, you need to copy and paste the Web Widget script in Zendesk Support.
- Click the Admin icon (
) in the sidebar, then select Channels > Widget.
- Click the Setup tab, if it is not already selected.
- Under the code box, click Copy to clipboard.
- In your HTML editor, paste the script before the closing </body> tag. For example:
<!DOCTYPE html> <html lang="en"> <head> <title>Hello, World!</title> </head> <body> <p>Hello, World!</p> <!-- Start of Zendesk Widget script --> <script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_SNIPPET_KEY"> </script> <!-- End of Zendesk Widget script --> </body> </html>
By default, the Web Widget is displayed on the bottom right of your web page.

Using API settings to customize the Web Widget
Next, you’ll use the API settings to change some common Web Widget properties. You access the API settings using JavaScript in the source code of your website. You can add the scripts directly to your web page, or maintain them in a separate folder and link to them from the web page. For the purposes of this tutorial, we’ll add scripts directly to the web page.
window.zESettings = {
webWidget: {
setting,
setting,
...
}
};
The syntax can vary for API settings. For example, the offset API setting has multiple property value pairs, and channel-specific settings such as the attachment API setting for Contact Form contains a child object.
The window.zESettings
object must be added before the Web Widget snippet in a web page, so the settings can be applied before the Web Widget is loaded.
In the following sections, you’ll use core settings to change the color of the Web Widget and to reposition it. For a complete list of core settings, see the Web Widget API documentation.
Changing the Web Widget color
color
setting. The theme
property accepts HEX codes. For example:
<script type="text/javascript">
window.zESettings = {
webWidget: {
color: { theme: '#78a300' },
}
};
</script>
To change the Web Widget color
<!DOCTYPE html>
<html lang="en">
<head>
<title>Hello, World!</title>
<meta charset="utf-8">
</head>
<body>
<p>Hello, World!</p>
<script type="text/javascript">
window.zESettings = {
webWidget: {
color: {
theme: '#78a300'
}
}
};
</script>
<!-- Start of Zendesk Widget script -->
<script id="ze-snippet" src="https://static.zdassets.com/ekr/YOUR_SNIPPET_KEY">
</script>
<!-- End of Zendesk Widget script -->
</body>
</html>
The Web Widget color on the web page should be green.

Changing the Web Widget position
Next, you'll reposition the Web Widget on the web page to be 100px from the bottom and 100px from the right. You can reposition the widget using the offset setting.
To change the Web Widget position
offset
setting to the existing window.zESettings
object, setting the horizontal
and vertical
parameters to 100px
. Make sure you don’t forget to add a comma after the color setting. For example:
<script type="text/javascript">
window.zESettings = {
webWidget: {
color: { theme: '#78a300' },
offset: { horizontal: '100px', vertical: '100px' }
}
};
</script>
The web page should display the repositioned Web Widget.

Using API commands to customize the Web Widget
zE('webWidget:<action>', '<event|property>', <parameters>);
where
-
<action> is a Web Widget setting or action
-
<event|property> is a property or event associated with the setting or action
-
<parameters> is an argument or value associated with the event or property.
Note: All API commands must be placed after the Web Widget snippet in your web page source code.
In the following sections, you’ll use core commands to set the locale of the Web Widget and to hide it. For a complete list of core commands, see the Web Widget API documentation.
Setting the Web Widget locale
By default, the Web Widget displays the language that matches the header of the web browser. In this instance, we would like to change the Web Widget locale to French.
The setLocale command sets the language for the Web Widget. Supported locales are shown in https://support.zendesk.com/api/v2/rosetta/locales/public.json.
To change the locale
setLocale
command between script tags after the Web Widget snippet:
<script type="text/javascript">
zE('webWidget', 'setLocale', 'fr');
</script>
The Web Widget language on the web page should display in French.

Hiding the Web Widget
Next, you'll create a button to hide the Web Widget using the hide
command. It can also be used to hide the Widget before the page loads.
To create a button to hide the Web Widget
hide
command using button tags:
<button onclick="zE('webWidget', 'hide')">Hide Web Widget</button>
The Hide Web Widget button should be displayed on the web page. Clicking on the button hides the Web Widget.

After configuring your Web Widget, your HTML file should look something like this:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Hello, World!</title>
<meta charset="utf-8">
</head>
<body>
<p>Hello, World!</p>
<script type="text/javascript">
window.zESettings = {
webWidget: {
color: {
theme: '#78a300'
},
offset: {
horizontal: '100px',
vertical: '100px'
},
};
</script>
<!-- Start of Zendesk Widget script -->
<script id="ze-snippet" src="https://static.zdassets.com/ekr/YOUR_SNIPPET_KEY">
</script>
<!-- End of Zendesk Widget script -->
<script type="text/javascript">
zE('webWidget', 'setLocale', 'fr');
</script>
<button onclick="zE('webWidget', 'hide')">Hide Web Widget</button>
</body>
</html>
10 Comments
This is particularly helpful. Thank you Darren. Particularly for specifying where to position the window.zESettings object and the API commands relative to the Zendesk Widget script. I think I was getting hung up by doing that wrong.
Hi David,
Thanks for the feedback. I'm glad you found it helpful!
Darren Chan how are you ?
Im using the Zendesk Web Widget in an existing application, but always that the page fire an ajax request, the "help" widget disapear.
Did you have this problem ? Which suggestion could you tell me to diagnostic and solve this error ?
Thanks.
Hi Renan -- without having your code or a page that reproduces this, it's hard to say exactly what's happening. If you post a distilled/very-simplified example that shows the behavior, we could maybe figure it out.
My guess is that your AJAX request has a side effect of reloading the page or manipulating its DOM in some way where the widget's snippet is somehow removed or affected.
Hi David,
I just want to open my widget when I clicking on the button. However, my code does not work. Can you help me?
<!DOCTYPE html>
<html lang="en">
<head>
<title>Hello, World!</title>
</head>
<body>
<p>Hello, World!</p>
<script type="text/javascript" id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=abc"> </script>
<script type="text/javascript">
window.zESettings = {
webWidget: {
helpCenter: {
chatButton: {
fr: 'Discutez avec une personne',
'*': 'Chat with a person now'
}
}
}
};
zE('webWidget', 'helpCenter:setSuggestions', { search: 'credit card' });
zE('webWidget', 'setLocale', 'en');
zE('webWidget', 'hide');
function openHelpDesk() {
zE('webWidget', 'open');
}
</script>
<!-- Start of Zendesk Widget script -->
<!-- End of Zendesk Widget script -->
<button onclick="zE('webWidget', 'open')">Open Web Widget</button>
</body>
</html>
Hi Khoa! If you are hiding the widget on page load, you will first need to show the widget and then you can open it. I haven't tried this with an onclick event, but I'm thinking that this should work:
Let me know if that works for you!
Thanks for your support, Greg! It works!
One more question: Can we customize the label field in a contact support form?
Exp: Email address, Your name..etc.
Thanks.
Darren Chan
Thank you for providing this.
-------------------------------------------------------------------
I have taken the liberty of distilling this down and creating a tip in the Support Community called "What to add Web Widget Code?"
https://support.zendesk.com/hc/en-us/community/posts/360046749634-Where-to-add-Web-Widget-Code-
--------------------------------------------------------------------
Also, if you are interested, I have some suggestions for making your post even better. Such as making things a little more clear and cleaning up some grammar.
Let me know if you are interested.
The company that we hire to test our site for accessibility concerns has flagged the Zendesk widget for a number of problems.
Hi Luke Grannis,
Thanks for your message. We appreciate you highlighting areas where we can make the Web Widget more accessible. Just to let you know, we're planning to dedicate some time to Accessibility later in the year with a focus on alt text & form fields within the Web Widget. Unfortunately, the three items you raised weren't on that list but I'll make a note of them on our side and we'll do our best to address them as soon as we can. Unfortunately, I can't provide an exact timeframe but I'll record your details and reach out when there's news.
Thanks for taking the time!
- Miranda.
Please sign in to leave a comment.