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>

Talk settings

The widget's talk object, which represents the Talk component, has the following setting:

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    talk: {
      nickname: 'Sales Support'
    }
  }
};
</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, itself with different properties to fully customize several of the widget's elements using color HEX codes as their value.

The theme property may be used as a base, determining the overall color scheme of the widget:

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

You can define a number of additional options to target specific elements:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    color: {
      theme: '#FF69B4',
      launcher: '#CC3A83',
      button: '#8A0648',
      resultLists: '#691840',
      header: '#203D9D',
      articleLinks: '#FF4500'
    }
  }
};
</script>

None of these elements are mandatory, and elements that are not defined will be based on either the theme color or the color defined in the settings page, in that order of priority.

Examples of elements customized using color properties:

Widget launcher

Search results

Article view

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
nickname

An admin can choose to set up more than one configuration for how Talk behaves in the Web Widget. Each configuration can customize call routing and display options. The nickname property tells the Web Widget which of the available configurations to use on the current page.

The value of the nickname property must match exactly the nickname of the Talk configuration you want to use, including any spaces and capitalization.

The nickname is publicly visible to anyone who looks at the page source code, so create the nickname accordingly.

Availability
  • talk

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    talk: {
      nickname: 'Sales Support'
    }
  }
};
</script>
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>

To specify an offset for mobile devices, add a mobile property to the offset object, and specify horizontal and vertical values. Example:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    offset: {
      horizontal: '100px',
      vertical: '150px',
      mobile: {
        horizontal: '230px',
        vertical: '100px'
      }
    }
  }
};
</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
  • talk

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