How can I customize the Zendesk Chat widget using the JavaScript API?

Question

Answer

Use the JavaScript API to make changes and customizations to the Web Widget (Classic) that is localized to one site or page.

If you are a beginner, the first thing to do is to figure out if you use the Web Widget (Classic) or Web Widget code snippet on your page. Both of these offer Chat functionality and can look the same to the visitor of the site.

Knowing the different code snippets

The Chat code snippet looks like this:

<!--Start of Zendesk Chat Script-->
<script type="text/javascript">
window.$zopim||(function(d,s){var z=$zopim=function(c){z._.push(c)},$=z.s=
d.createElement(s),e=d.getElementsByTagName(s)[0];z.set=function(o){z.set.
_.push(o)};z._=[];z.set._=[];$.async=!0;$.setAttribute("charset","utf-8");
$.src="https://v2.zopim.com/?ACCOUNT_KEY";z.t=+new Date;$.
type="text/javascript";e.parentNode.insertBefore($,e)})(document,"script");
</script>
<!--End of Zendesk Chat Script-->

The ACCOUNT_KEY is the only unique identifier to your account. If you started with a Chat only account, this is the code snippet you have.

The Web Widget code snippet looks like this:

<script id="ze-snippet" 
src="https://static.zdassets.com/ekr/snippet.js?key=ACCOUNT_KEY"> </script>

The ACCOUNT_KEY is the unique identifier, however this is a different format than a Chat account key. If you started your Chat account from within your Support account, this applies to you.

The only way to know for sure is to open your account and check the Widget page to see what your account's exact widget snippet is.

Adding some custom JavaScript

The most common issue with using our JavaScript API is that events are not set up to execute in the correct order. JavaScript usually runs asynchronously on a page, so without proper care, it's possible the command to, for example, change the color of the widget is executed before the widget exists. For this reason, adding the correct "ready" functions is imperative to having a reliable customization.

Web Widget (Classic) code

In this case, your custom code should look something like this:
```
$zopim(function(){
    // Custom code here
  });
```
This snippet waits for the page to finish loading, then for the Web Widget (Classic) to finish loading, before adding any customization.

Web Widget code

Use the script below:

  zE(function(){
    $zopim(function(){
      // Custom code here
    });
  });

In this example, the code is waiting for the page to load, then for the Web Widget to load, and finally for the Web Widget to load the Chat functionality. After Chat loads, it's safe to add any customizations you wish to the Web Widget (Classic).

For more information, see these articles: