Settings reference

This page documents all the available settings of the window.zESettings object. The window.zESettings object is loaded only when the widget boots. If you need to update the settings at run-time, please use the updateSettings API.

Each setting may be available in one or more objects. For example, the title setting is available for the chat, talk, contactForm and helpCenter objects, and can be set independently in each.

The following example shows the offset property of the webWidget parent object:

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

The following example shows the departments setting of the chat child object:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      departments: {
        enabled: ['finance', 'hr', 'sales']
      }
    }
  }
};
</script>

Available settings:

attachments

Disables attaching files to tickets submitted through the Web Widget.

Availability

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

authenticate

Gives the user access to restricted Help Center content.

Availability
Usage

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.

To use authentication for chat, you must configure the Web Widget settings in the chat 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 for authenticated chat.

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

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

<script type="text/javascript">
zE(function() {
  zE.logout();
});
</script>

badge

The badge setting has the following properties:

Property Type Description
label object Sets the label of the badge
image string Sets the image of the badge
layout string Sets the layout of the badge
Availability
badge.label

Sets the label of the badge. Will only show if the label is allowed in the layout.

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.

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      badge: {
        label: {
          '*': 'Chat with us',
          'fr': 'Discute avec nous'
        }
      }
    }
  }
};
</script>
badge.image

Sets the image of the badge. Will only show if the image is allowed in the layout.

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      badge: {
        image: 'https://example.com/img/avatar.jpg'
      }
    }
  }
};
</script>
badge.layout

Sets the layout of the badge. Valid values are 'image_right', 'image_left', 'image_only' and 'text_only'. If an invalid value is used it will default to 'image_right'.

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      badge: {
        layout: 'image_only'
      }
    }
  }
};
</script>
All together

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    launcher: {
      badge: {
        label: {
          '*': 'Chat with us',
          'fr': 'Discute avec nous'
        },
        image: 'https://example.com/img/avatar.jpg',
        layout: 'image_left'
      }
    }
  }
};
</script>

chatButton

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

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

The string can't exceed 25 characters.

Availability

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      chatButton: {
        'fr': 'Discute avec nous',
        '*': 'Chat with us'
      }
    }
  }
};
</script>
Related settings

chatLabel

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

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

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

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

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.

Availability
Usage

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',
      launcherText: '#E589B7',
      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.

For accessibility, the Web Widget enforces a minimum contrast ratio between colors to ensure the widget meets a minimum 'AA' accessibility rating as specified by the Web Content Accessibility Guidelines (WCAG).

Set a custom combination of launcher and launcherText colors to control both the Widget's launcher button's background and foreground.

Examples of elements customized using color properties:

Widget launcher Example

Search results Example

Article View Example

Related settings

concierge

Set the chat concierge’s avatar, name, and title.

Availability

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      concierge: {
        avatarPath: 'https://example.com/img/avatar.jpg',
        name: 'Jane Doe',
        title: { '*': 'Live support' }
      }
    }
  }
};
</script>

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.

Contact 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

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

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

departments

The departments setting has the following properties:

Property Type Description
enabled array Displays the specified departments in the pre-chat form
select string Sets the visitor’s default department for the current session

The properties can be used singly or in any combination.

Availability
departments.enabled

Displays only the specified departments in the pre-chat form. All other departments are hidden regardless of their status.

Department names are matched in a case-insensitive manner.

If the department names or IDs passed in are invalid, the department dropdown menu will not show those options. If no value or valid or null is used, the dropdown won't appear.

Example

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      departments: {
        enabled: ['finance', 'hr', 'sales']
      }
    }
  }
};
</script>
departments.select

Sets the visitor’s default department for the current session.

Chat requests will be routed to this department unless the visitor selects another department in the pre-chat form or the department is offline.

Department names are matched in a case-insensitive manner.

If the department names or ID is invalid or null the department will be cleared.

Note: If the visitor has already started chatting, changes to the default department will not affect the department of the started chat. The changes to the default department will also not take effect until a page change or refresh. The department of the started chat will persist and be taken as the default department until a page change or refresh, even when the visitor has explicitly ended the chat.

Offline messages will also be routed to this department.

Example

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      departments: {
        select: 'hr'
      }
    }
  }
};
</script>
All together

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      departments: {
        enabled: ['finance', 'hr', 'sales'],
        selected: 'hr'
      }
    }
  }
};
</script>

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

Availability
Usage

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.

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

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.

Label 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

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.

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

The string can't exceed 25 characters.

Availability

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

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    talk: {
      nickname: 'Sales Support'
    }
  }
};
</script>

notifications

Determines if notifications should show on mobile.

Availability

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

offset

Moves the Web Widget vertically and horizontally.

Availability
Usage

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.

Original Article Button Example

Availability

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

offlineForm

Set the offline form greeting message.

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

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      offlineForm: {
        greeting: {
          '*': "We aren't online right now, please leave a message",
          'fr': "Nous ne sommes pas en ligne pour le moment, s'il vous plaît laissez un message"
        }
      }
    }
  }
};
</script>

prechatForm

Set the prechat form greeting message or the department label.

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

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    chat: {
      prechatForm: {
        greeting: {
          '*': 'Please fill out the form below to chat with us',
          'fr': "S'il vous plaît remplir le formulaire ci-dessous pour discuter avec nous"
        },
        departmentLabel: {
          '*': 'Select a department',
          'fr': "S'il vous plaît remplir le formulaire ci-dessous pour discuter avec nous"
        }
      }
    }
  }
};
</script>

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.

Availability
Usage

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

Search Placeholder Example

Availability

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.

Select Ticket Form Example

Availability

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      selectTicketForm: {
        '*': 'Please choose:'
      }
    }
  }
};
</script>
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

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

suppress

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

Availability

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

tags

In contactForm, adds one or more tags to any ticket created with the Web Widget.

In chat, adds one or more tags to the visitors chat session.

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

Availability

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

ticketForms

Specifies one or more ticket forms for the contact form.

Availability
Usage

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'
        }
      }
    ]
  },
  ...
]

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.

Title 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

Example
<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      title: {
        'en-US': 'Search for help',
        'fr': 'Recherche d\'aide'
      }
    },
    contactForm: {
      title: {
        '*': 'Feedback'
      }
    },
    chat: {
      title: {
        '*': 'Chat with us!',
        'pl': 'Czat na żywo'
      }
    }
  }
};
</script>
Related settings

zIndex

Specifies the stack order of the Widget on the page.

Availability
Usage

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

analytics

Specifies whether to enable or disable Google Analytics tracking.

Note: The currently supported events can be found here

Availability
Usage
<script type="text/javascript">
window.zESettings = {
  analytics: true
};
</script>

errorReporting

The Web Widget sends any errors that occur to a reporting service used by Zendesk to help diagnose and address issues. This error reporting can be disabled setting errorReporting to false.

Availability
Usage
<script type="text/javascript">
window.zESettings = {
  errorReporting: true
};
</script>