Using the Chat widget JavaScript API

Have more questions? Submit a request


  • Bharath Kashyap

    Hi Niall,


    Quick question..!

    Does this syntax work ?



    Am looking to customize my web widget through JS. But am not able get hold of the syntax to make widget & JS talk to each other. 

    Let me know how could I make JS functions work for Web widget please.


  • Dan Ross

    Hey Bharath,


    At first glance, it looks like you need to wrap those zopim calls in a zE(function() (see bold text below) for them to work as you're expecting. 


    }); });
  • Bharath Kashyap

    Hi Dan, 

    Much Appreciated with your help. 

    This is a code, checking if simple code works, but cannot see its reflection on chat widget. Any thoughts on this ?


    Widget color 



  • Dan Ross

    Hey Bharath,

    According to the docs, $zopim.livechat.theme.reload(); needs to be called after button.setColor is invoked. Please add that line after your line setting the color. Worth noting that the docs also list button.setColor as deprecated, you may want to consider using the latest function instead.


    If that doesn't work, please post any messages you might be getting in your browser's console log. 

    Good luck!

  • Bharath Kashyap

    Hi Dan, 


    Tried this 


    This is message from Console.

  • Dan Ross

    Hey Bharath,


    I'm not sure what adrum.js is, but I think it's independent of this issue. The line you highlighted is a standard message and not an error.  I just saw you have this chat module and API calls in your home_page.hbs file, could you try putting it in your document_head.hbs template? I'm not certain it will make a change, but I don't see anything else that looks wrong in what you've posted.

  • Solvvy, Inc

    Hi Dan, 

     When I try the new web widget API's callback options they don't seem to be working as expected for migrating from the old zopim API's. Consider the following example:

    <script type="text/javascript">
    // Custom code here
    zE('webWidget:on', 'chat:status', function(status) {
    console.log('This chat session is now', status);
    $zopim.livechat.setOnStatus(status=> {
    console.log('This zopim chat session is now', status);


    1. This only prints the zopim chat session logs on change in status. The example code for web widget was picked from the documentation

    2. The page that documents equivalent migrations for the API's seems to differ from the actual API documentation. Eg:

    In the above link it shows zE('webWidget:on', 'chat.status', (status) => {})

    while in the widget api document it says zE('webWidget:on', 'chat:status', function(status<string>) {});

    Note the colon instead of dot between chat and status. I've tried both and neither worked in the above example.

    I've tried zopim and web widget separately too and they still haven't worked.

    3. The Zendesk webwidget script for our organisation is just a single line that goes something like

    <script id="ze-snippet" src="">

    Is that causing any problems?





  • Dan Ross

    Hey Solvvy,

    I've not checked out the newer Chat APIs yet, but it's on my to-do list to migrate. The fact that the docs differ is never a good sign. I don't actually work for Zendesk, so I won't be able to tell you what the correct method to use would be - you may want to drop a ticket to them and show them the inconsistency in the docs and see if they can get you an answer as to which of them is the correct one to use.

    I don't see anything wrong with your syntax though, so it seems like its an issue with the API not delivering what you're expecting it to. 

    Sorry that wasn't more helpful. If you check with their Support team and get an answer that works, please come back and share, I imagine many people would be interested in the correct method!

  • Henry

    Hi! Question about this... We have an old, deactivated implementation of Zendesk lying around on our site, using the Web Widget code snippet listed above. We are currently attempting to re-implement Zendesk on specific pages only, and the Zendesk chat experience now lists an entirely different code snippet from the two listed above:

    <!-- Start of Zendesk Widget script -->
    <script id="ze-snippet" src="[OUR_APP_KEY]"> </script>
    <!-- End of Zendesk Widget script -->

    The issue seems to be that when we turn on the chat through the Zendesk admin console, the old snippet activates and displays the chat widget on every page of our application (this is not the desired behavior). The question here, then, is: Can I remove safely the old Zendesk snippet in favor of the one listed above (which will only render on the specific pages we want the chat on), and still have zendesk chat work properly?

    Looking at what is returned from the "snippet.js" in the widget code pasted above, it feels like specifically embedding either the web or chat widgets directly is no longer necessary, I just want to confirm.

  • Sean Bischoff

    My code looks like neither. From your Agent Settings Web Widget code box:

    <!-- Start of winehelp Zendesk Widget script -->
    <script id="ze-snippet" src=""> </script>
    <!-- End of winehelp Zendesk Widget script -->

    No calls with zE() work. zE is undefined.

  • Brett - Community Manager

    @Henry do you know if you're using a Standalone Chat account that's integrated with your Support account? If so, that may explain why your code snippet looks different on your end.

    @Sean what sort of calls are you looking to make to your widget? Any additional information you have is greatly appreciated :)


  • Donald Moore

    I'm calling ...

    zE(function () { zE.activate(); });

    ... when a component loads in my web application and the Chat widget covers the screen as a blank white div. I had to disable a popup blocker but that didn't fix the problem. Help?


  • Brett - Community Manager

    Hi Donald,

    Is the site your posting your code snippet public? If so, can you provide a link to where your Chat widget is hosted so we can take a look for you?

    Thanks in advance!

  • Donald Moore

    Brett, I created a temporary fix using a call to setTimeout

    setTimeout(() => { zE(function () { zE.activate(); }); },10000) 

    Basically, zE.activate() is getting called before the widget is rendering. Then, when the widget renders, it renders as a blank white div that covers the viewport. It takes about 5 seconds for the widget to render. You will see the page for a brief moment, then it will go blank.

    I'll create a dummy page so you can see it. It only happens on mobile. You can use the Chrome dev tools with the mobile device emulator to test it.

    Update: I've noticed that when the device isn't mobile, `sometimes` the chat widget will not render altogether when activate() is called before it renders.

    Update 2: I've also noticed that this doesn't happen in Edge, which is strange because I thought Edge switched to Blink about a year ago.

    Update 3: It worked the first time in Edge. Didn't work the second time. Same thing for the simulator. Worked the first time. I refreshed. Blank div.

  • Brett - Community Manager

    Hey Donald,

    So this is what I see on my end when I navigate to the URL you provided on my mobile device:

    I've tested this in both Safari and Chrome on my mobile device and received the same results.

    Are there any other steps I should be taking to try and replicate?

  • herman herman

    anyone can help me?
    Widget for Web
    <!-- Start of Zendesk Widget script -->
    <script id="ze-snippet" src="> </script>
    <!-- End of Zendesk Widget script -->
    I have entered this widget and succeeded for the website version.


    for the mobile version I enter the widget code as follows:

    but it doesn't work properly ... can anyone ask for the widget code for the mobile version?

  • Brett - Community Manager

    Hey Herman,

    I reached out to one of our Chat experts and I've been informed that you should use the same code snippet for both Web and Mobile. Therefore you'll want to use the code snippet that's working in your web browser with your mobile version.

    Hope this helps!

  • Roman Sheydvasser

    I couldn't find this documented anywhere else, so wanted to make a note here since this article is about required steps for using API methods.

    In addition to the code above for checking that the web widget and chat widgets are loaded, the updatePath web widget api method ( wouldn't work without putting it inside a chatConnected method like so:

    zE('webWidget:on', 'chat:connected', function() {
    zE('webWidget', 'updatePath', {
    url: supportUrl,
    title: supportTitle
  • Zachary Dugas

    Hi Zendesk Community,

    We are experiencing problems with our custom code and the various browsers customer use, specifically Edge and Internet Explorer. Any insight would be greatly appreciated as Zendesk support has been unsuccessful in providing a solution. 

    After further testing with IE and Edge I noticed the below.


    • Does not require department selection – a user can simply slide into a chat if someone is online

    Internet Explorer:

    • There is a department selection – but we can still choose Dealer NA on the website
    • This means the code is not working

    Here is the code:

    $(document).ready(function () {
    zE(function () {
    $zopim(function () {
    // Calls function to get browser language
    const currentLanguageCode = getCurrentLanguageCode();

    // Gets language from url path
    if (window.location.href.indexOf("/fr-CA") > -1) {
    currentLanguageCode = "fr-ca";

    if (currentLanguageCode == "fr-ca") {
    language: "fr"

    $zopim.livechat.setOnConnected(function () {
    // Chat is in it's own iframe, so must access that
    const chatIframe = $(".zopim iframe");

    // Include Chat departments you want to display for each locale
    // Department names on left side of colon must match exactly to those in Chat settings
    // Translations on right side of colon - if no translation necessary, just copy department name as-is to right side
    // See full list of language codes here:
    const translatedDepartmentNames = {
    "en-US": {
    "Carriers & Racks product selection": "Carriers & Racks product selection",
    "Order questions": "Order questions",
    "Technical support": "Technical support",
    "Active with Kids product selection": "Active with Kids product selection",
    "Packs, bags & luggage product selection": "Packs, bags & luggage product selection",
    "Keys & locks": "Keys & locks",
    "Warranty questions": "Warranty questions"
    "sv": {
    "Orderfrågor": "Orderfrågor",
    "Produktfrågor": "Produktfrågor",
    "Nycklar & reservdelar": "Nycklar & reservdelar"
    "da": {
    "Produkt spørgsmål": "Produkt spørgsmål",
    "Bestil spørgsmål": "Bestil spørgsmål",
    "Nøgler og reservedele": "Nøgler og reservedele"
    "fr-ca": {
    "Carriers & Racks product selection": "Sélection de produits supports et porte-charges",
    "Order questions": "Commandes",
    "Technical support": "Support Technique",
    "Active with Kids product selection": "Sélection de produits famille active",
    "Packs, bags & luggage product selection": "Sélection de produits bagages et sacs",
    "Keys & locks": "Clés et verrous",
    "Warranty questions": "Garantie"

    const currentLanguageTranslatedDepartmentNames =
    translatedDepartmentNames[currentLanguageCode || "en-US"]; // default to en-US if no entry found for user locale

    const allDepartments = $zopim.livechat.departments.getAllDepartments();

    // Only display departments listed in
    const departmentsFilteredForLocale = $zopim.livechat.departments.filter.apply(

    // for each department, replace the name in the select dropdown with the translated name
    allDepartments.forEach(department => {
    .find("option[value='" + + "']")

    // also replace the selected name in the select dropdown placeholder
    .find("select[name='department_id'] option:selected")

    // Checks the browser language regardless of the version of the site they are on
    function getCurrentLanguageCode() {
    return window.navigator.languages ?
    window.navigator.languages[0] :
    window.navigator.userLanguage || window.navigator.language;


Please sign in to leave a comment.

Powered by Zendesk