Settings

You can specify various settings for the Web Widget by defining a window.zESettings object. Example:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    offset: { horizontal: '100px', vertical: '150px' }
  }
};
</script>

Make sure to specify any setting before the Web Widget snippet.

For an overview of how the Web Widget works, see Understanding the end-user experience in the Support Help Center.

General settings

The Web Widget has the following general settings:

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    color: { theme: '#78a300' }
  }
};
</script>

Contact form settings

The widget's contactForm object, which represents the contact form, has the following settings:

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      attachments: false
    }
  }
};
</script>

Contact options settings

The widget's contactOptions object, which represents a component that lets the user choose between starting a chat or submitting a ticket, has the following settings:

To learn more about contact options, see Offering end-users multiple contact options in the Support Help Center.

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactOptions: {
      enabled: true,
      contactButton: { '*': 'Get in touch' }
    }
  }
};
</script>

Help Center settings

The widget's helpCenter object, which represents the Help Center component, has the following settings:

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      chatButton: {
        'fr': 'Discutez avec une personne',
        '*': 'Chat with a person now'
      }
    }
  }
};
</script>

Chat settings

The widget's chat object, which represents the Chat component, has the following setting:

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      suppress: true
    }
  }
};
</script>

Launcher settings

The widget's launcher object, which represents the launcher button, has the following settings:

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      chatLabel: {
        '*': 'Chat now'
      }
    }
  }
};
</script>

Settings reference

attachments

Disables attaching files to tickets submitted through the Web Widget.

Availability
  • contactForm
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      attachments: false
    }
  }
};
</script>
Related Settings
authenticate

Gives the user access to restricted Help Center content. To use this setting, you must configure the Web Widget settings in the admin interface, and then create a JWT token based on a shared secret generated by the configuration. For details, see Setting up the Web Widget to show restricted content.

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    authenticate: { jwt: 'YOUR_JWT_TOKEN' }
  }
};
</script>

Tokens expire after two hours. You can remove them from local storage sooner by running the following function when the user logs out:

zE(function() {
  zE.logout();
});
chatButton

Replaces the default string on the button in the Help Center form that opens the Chat interface.

example

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

The string can't exceed 25 characters.

Availability
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      chatButton: {
        'fr': 'Discutez avec une personne',
        '*': 'Chat with a person now'
      }
    }
  }
};
</script>
Related settings
chatLabel

Replaces the default string on the launcher button when Chat is enabled and Help Center is not.

example

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • launcher
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      chatLabel: {
        '*': 'Chat now'
      }
    }
  }
};
</script>
Related setting
chatLabelOffline

Replaces the default string that informs the user that chat is unavailable when contactOptions is enabled.

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactOptions
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactOptions: {
      enabled: true,
      chatLabelOnline: { '*': 'Live Chat' },
      chatLabelOffline: { '*': 'Chat is unavailable' }
    }
  }
};
</script>
Related settings
chatLabelOnline

Replaces the default string of the link that lets a user start a chat when contactOptions is enabled.

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactOptions
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactOptions: {
      enabled: true,
      chatLabelOnline: { '*': 'Live Chat' }
    }
  }
};
</script>
Related settings
color

Sets a color theme for the Web Widget. The color property consists of an object with a theme property with color HEX codes as possible values.

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    color: { theme: '#78a300' }
  }
};
</script>
Related settings
contactButton

Replaces the default string on the button that opens the contact options component, which lets the user choose between starting a chat or submitting a ticket.

example

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactOptions
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactOptions: {
      enabled: true,
      contactButton: { '*': 'Get in touch' }
    }
  }
};
</script>
Related settings
contactFormLabel

Replaces the default string of the link that lets the user submit a ticket when contactOptions is enabled.

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactOptions
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactOptions: {
      enabled: true,
      contactFormLabel: { '*': 'Leave us a message' }
    }
  }
};
</script>
Related settings
fields

Pre-populates the value of one or more text fields in the contact form.

Note: The API doesn't support pre-populating drop-down fields. However, you can set default values for custom drop-down fields in the Support admin interface (Manage > Ticket Fields).

For a default system field, specify the field name as the field id. Example:

fields: [
  { id: 'description', prefill: { '*': 'My text' } }
]

For a custom field, specify the custom field's id as the id. To get the id, see List Ticket Fields in the Zendesk API docs. Example:

fields: [
  { id: 2142225, prefill: { '*': 'My text' } }
]

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactForm
Example
<script type="text/javascript">
zESettings = {
  webWidget: {
    contactForm: {
      fields: [
        { id: 'description', prefill: { '*': 'My field text' } },
        { id: 2142225, prefill: { '*': 'My custom field text' } }
      ]
    }
  }
};
</script>
Related settings
filter

Limits Help Center search results to a specified category, section, or label. The filter property consists of an object with a category, section, or label property.

Availability
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      filter: {
        section: '200154474'
      }
    }
  }
};
</script>

For more examples, see Limiting search results in the Zendesk Support Help Center.

Related settings
label

Replaces the default string on the launcher button.

example

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • launcher
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      label: {
        'en-US': 'Need help?',
        'fr': 'Besoin d\'aide?'
      }
    }
  }
};
</script>
Related setting
messageButton

Replaces the default string on the button in the Help Center form that opens the contact form.

example

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

The string can't exceed 25 characters.

Availability
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      messageButton: {
        '*': 'Contact us now.'
      }
    }
  }
};
</script>
Related settings
offset

Moves the Web Widget vertically and horizontally. The offset property consists of an object with horizontal and vertical properties with '##px' string values.

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    offset: { horizontal: '100px', vertical: '150px' }
  }
};
</script>
Related settings
originalArticleButton

Hides the "View Original Article" button.

Availability
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      originalArticleButton: false
    }
  }
};
</script>
Related settings
position

Positions the Web Widget on the left side of the page instead of the right side, and on the upper side instead of the lower side. The position property consists of an object with horizontal and vertical properties. The possible value for horizontal is 'left' (the default is right). The possible value for vertical is 'top' (the default is bottom).

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    position: { horizontal: 'left', vertical: 'top' }
  }
};
</script>
Related settings
searchPlaceholder

Replaces the placeholder text displayed in the Help Center search box that says "How can we help?"

Availability
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      searchPlaceholder: {
        '*': 'Search our Help Center',
        'fr': "Cherchez dans le centre d'aide"
      }
    }
  }
};
</script>
Related settings
selectTicketForm

Replaces the text in the contact form that prompts the end user to select a ticket form when more than one form is available. See ticketForms. The default text is "Please select your issue".

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactForm
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      selectTicketForm: {
        '*': 'Please choose:'
      }
    }
  }
};
</script>

image

Related settings
subject

Inserts a Subject field in the contact form. The form doesn't have one by default to enhance the user experience and conserve space in the Web Widget.

Availability
  • contactForm
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      subject: true
    }
  }
};
</script>
Related settings
suppress

Suppresses the Help Center, Chat, or contact form in the Web Widget on that page.

Availability
  • chat
  • contactForm
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      suppress: true
    },
    helpCenter: {
      suppress: true
    }
  }
};
</script>
tags

Adds one or more tags to any ticket created with the Web Widget.

Note: The tags are visible in the JavaScript console in the user's browser.

Availability
  • contactForm
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      tags: ['website', 'store']
    }
  }
};
</script>
Related settings
ticketForms

Specifies one or more ticket forms for the contact form. If you list more than one ticket form, a dropdown menu appears in the contact form prompting the end user to select a form. You can change the text that prompts the end user with the selectTicketForm object.

Ticket forms are listed by id. Example:

ticketForms: [
  {id: 426353},
  {id: 429981}
]

To get a ticket form id, see List Ticket Forms in the Zendesk API docs.

You can include the fields object to pre-populate one or more fields in one or more ticket forms. Example:

ticketForms: [
 {
   id: 426353,
   fields: [
     {
        id: 'description',
        prefill: {
          '*': 'My field text'
        }
      }
    ]
  },
  ...
]
Availability
  • contactForm
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      ticketForms: [
        { id: 426353 }
      ]
    }
  }
};
</script>
Related settings
title

Replaces the default title string with a custom string.

example

You can use different strings for different locales or use one string for all locales by using an asterisk (*) for the locale. You can also use the asterisk to specify a fallback string in case the browser isn't set to a listed locale.

Availability
  • contactForm
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      title: {
        'en-US': 'Search for help',
        'fr': 'Recherche d\'aide'
      }
    },
    contactForm: {
      title: {
        '*': 'Feedback'
      }
    }
  }
};
</script>
viewMore

Hides the View More button that may appear after a Help Center search. The button appears when the search returns more than 3 articles.

Availability
  • helpCenter
Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      viewMore: false
    }
  }
};
</script>
Related settings
zIndex

Specifies the stack order of the Widget on the page. When two elements overlap, the z-index values of the elements determine which one covers the other. An element with a greater z-index value covers an element with a smaller one.

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    zIndex: 999999
  }
};
</script>
Related settings