1. Zendesk Develop
  2. Zendesk embeddables
  3. Web Widget

Quickstart – Web Widget JavaScript APIs

Darren Chan
  • Updated

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

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

  1. In your web browser, go to https://codepen.io/pen/.
  2. In the top UI pane, click Change View, and select the left view option.
  3. In the HTML editor on the top right side, click the dropdown menu, and select Maximize HTML Editor.
  4. 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.

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Setup tab, if it is not already selected.
  3. Under the code box, click Copy to clipboard.
  4. 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.

The basic JavaScript syntax for API settings is as follows: 
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

In this example, the Web Widget’s default blue color will be changed to green using the theme property of the 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

In the HTML editor, paste the script in bold after the header tags, but before the Web Widget snippet. 
<!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

In the HTML editor, add the 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

Commands let you customize some Web Widget general settings and functions embedded in the Web Widget. It follows the following basic syntax: 
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

In the HTML editor, add the following 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

In the HTML editor, between the body tags, add the following 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>
Have more questions? Submit a request

12 Comments

Sort by Date Votes
  • David Lance
    Comment actions Permalink

    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.

    0
  • Darren Chan
    Comment actions Permalink

    Hi David,

    Thanks for the feedback. I'm glad you found it helpful!

    0
  • Renan
    Comment actions Permalink

    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.

    0
  • Bryan - Community Manager
    Comment actions Permalink

    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.

    0
  • Khoa
    Comment actions Permalink

    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>

    0
  • Greg - Community Manager
    Comment actions Permalink

    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:

    <button onclick="zE('webWidget', 'show');zE('webWidget', 'open')">Open Web Widget</button>

    Let me know if that works for you!

    1
  • Khoa
    Comment actions Permalink

    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.

    0
  • Alejandro Colon
    Comment actions Permalink

    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. 

    0
  • Luke Grannis
    Comment actions Permalink

    The company that we hire to test our site for accessibility concerns has flagged the Zendesk widget for a number of problems.  

    • The widget's title is using an h1 element.  Which means, when open, the page has 2 h1 elements.
    • After opening the widget, nothing within the widget receives focus, so it is very confusing for the visually impaired user.  Is there a recommended way of handling this?  I would think it would be the default behavior, ie the first interactive element in the zendesk widget getting focused.
    • Low contrast warning, related to drag and drop fields for attaching files.
    0
  • Miranda Burford
    Comment actions Permalink

    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.

    0
  • Joël van Amerongen
    Comment actions Permalink

    Hello, I don't understand why the badge image is not changeable.

    I have found this document: https://developer.zendesk.com/embeddables/docs/widget/core#launcher

    the webWidget.launcher.badge.image is not working, also webWidget.launcher.badge.layout = 'image_only' also not working.

    I have created this pen: https://codepen.io/jovana75/pen/JjWBYzm for testing.

    Thanks for any help.

    0
  • Alejandro Colon
    Comment actions Permalink

    Joël van Amerongen

    I believe I ran into this issue before. If I remember correctly, 

    webWidget.launcher.badge.image

    is only applicable to the chat launcher badge image. Hopefully, Zendesk can chime in here. 

    0

Please sign in to leave a comment.

Related articles

Related articles

Powered by Zendesk