English (US)
  1. Zendesk help
  2. Chat
  3. Live chat advice and troubleshooting
  4. How to manage the widget for live chat

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

Niall Colfer
  • Edited

Question

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

Answer

Use the JavaScript API to make changes and customizations to your Chat widget 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 Chat 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:


TheACCOUNT_KEYis 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:

TheACCOUNT_KEYis 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.

唯一确定的方法是打开你的亚柯unt 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.

  • Chat widget 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 Chat widget 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 Chat widget.

    Return to top

    11 Comments

    • Steven Howell

      Thanks for the article! I am working on migrating from the Zopim legacy chat widget to the new Web Widget. So we currently have the code snippet from your first example to initialize `window.$zopim` and use the `livechat` APIs.

      I see that these `livechat` APIs have been aliased according to your docs, and most should work without code changes.

      My one misunderstanding is this – should we be swapping out our existing code snippet for the new `ze-snippet` one before we migrate? Or can we continue to use our existing legacy snippet (assuming we migrate away from any unsupported livechat APIs), even after the migration? And if so, would we simply update our customizations from:

      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");

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

      to:

      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");
      // snippet above is the same, just with a `zE()` wrapper now
      zE(function(){ $zopim(function(){ // Custom code here }); });

      Thanks in advance.

      0
    • Romain Lebossé

      Is there a way to prevent the web widget from sending the user current url ? Or to rewrite it ? (in case the url contains some critical data) ?

      0
    • Scott Cavness 
      I determined I'm using the web widget (

      and I was led here from https://support.zendesk.com/hc/en-us/articles/4408828505754-Enabling-cookie-consent-for-the-Chat-widget,
      however, I'm not a javascript programmer and the above example does not show how to enable the cookie consent.
      I've tried several different options (before/after current script) using this link
      https://api.zopim.com/files/meshim/widget/controllers/liveChatAPI/CookieLawAPI-js.html
      but "no joy". A good working example of how to set up the consent in/around the current
      working script would be very helpful.
      0
    • Dane
      Zendesk Engineering
      Hi Scott,

      Please use the code below as reference. You can also refer toWeb Widget (Classic) API: Cookies.




      Hi Steven,

      As long as you are using the correct web widget code, it should work as it is but the customization from the previous Chat widget will not work until you follow the format for web widget.
      0
    • Mark L

      How do we customize the new Zendesk messenger widget using the Javascript API? I don't see any documentation on this?

      0
    • Tipene Hughes
      Zendesk Developer Advocacy

      Hey, Mark!

      Here's a link to the documentation for the messaging web widget:

      https://developer.zendesk.com/api-reference/widget-messaging/web/core/

      我们构建的特性和功能,期望to see more APIs added to the docs.

      0
    • Mark L

      Hi Tipene, thanks for responding. I've seen the documentation already. Unfortunately, the new messenger API is missing programmatic hiding and offset, which the previous chat API supported. We need this to hide the widget and apply a vertical offset on certain pages. We noticed these feature disparities during our upgrade process, hence we wanted to circumvent these issues by utilising DOM manipulation against the iframe using JavaScript. However, due to the async nature of JS, sometimes our code manipulates it before the iframe messenger widget is rendered. The provided messenger widget API documentation mentions nothing about this, whereas the above article supports this for the chat widget. What do you suggest to get around this issue?

      0
    • Mark L

      From my understanding, programmatic hide for messenger API is planned for 2023 release, based on other help threads. Do you have a release window for this yet? How about programmatic offset? Until these are implemented in the new messenger API, we need to rely on alternative solutions.

      0
    • Tipene Hughes
      Zendesk Developer Advocacy

      Hey Mark,

      Unfortunately I don’t have any specifics on when the additional APIs will be released. I’ll check in with the product team though and see if I can get any further information.

      In the meantime, here’s a basic example of how you could go about manipulating the web widget directly in the DOM. It makes use of the mutationObserver to watch for the widget being added to the DOM, then hides the widget in the UI. The div element is saved to a variable which can be used to change the display as needed, or add any styling such as positioning.

      let widgetContainer;

      const observer = new MutationObserver(function (mutations) {
      // Iterate over DOM mutation array
      mutations.forEach(function (mutation) {
      // Check if node has sibling and attribute
      if (!mutation.previousSibling || !mutation.previousSibling.attributes) {
      return null;
      }
      // Check if sibling node is web_widget div based off attribute
      else if (mutation.previousSibling.attributes[0].textContent === "web_widget") {
      // Save widget div to variable
      widgetContainer = mutation.addedNodes[0];

      // Hide widget div
      mutation.addedNodes[0].style.display = "none";

      // Stop observing DOM
      observer.disconnect();
      }
      });
      });

      observer.observe(document.body, {
      childList: true,
      });

      Keep in mind that there may be some specifics that need to be altered depending on your set up, but this will get you moving in the right direction.

      Feel free to reach out if you have any questions.

      Tipene

      0
    • Tipene Hughes
      Zendesk Developer Advocacy
      Hi again Mark, here's an update on this topic from another thread:

      https://support.zendesk.com/hc/en-us/community/posts/4409222686618-Unhide-hide-messaging-widget
      0
    • Mark L

      Hi Tipene, thanks for the update. Good to know that show/hide has finally been implemented.

      I've tried to use the MutationObserver approach above for programmatic vertical offset, however it's not very reliable, it only works sometimes when the DOM is fully loaded. Are there any alternative solutions?

      The previous Zendesk chat API had the updateSettings feature, which allowed us to pass a vertical offset. We have certain pages where the Zendesk widget at the bottom, and on mobile, would be interrupting our functionality. Hence, we want to have the programmatic offset ONLY on certain pages.

      0

    Pleasesign into leave a comment.

    Powered by Zendesk