Using custom ticket fields and ticket forms with the Web Widget

The Web Widget allows you to customize the information displayed in your contact form in a number of ways. In this article, we'll discuss the following customizations:

• Adding custom ticket fields to the widget's default contact form (available to all customers, on any Support plan).
• Using ticket forms with the widget (available to customers on the Enterprise plan, or the Professional plan with Productivity pack).

This article includes the following topics:

• Adding custom ticket fields to the default contact form
• Enabling ticket forms in the Web Widget
• Customizing field descriptions in the Web Widget
• Advanced customization: Contextual ticket forms
• Advanced customization: Pre-populating contact form text fields
• Advanced customization: Adding tags to tickets sent through the Web Widget from specific pages

Related articles:

• Using the Web Widget to embed customer service on your website
• Advanced customization of your Web Widget
• Creating ticket forms to support multiple request types
• Adding custom fields to your tickets and support request forms

Adding custom ticket fields to the default contact form

Customers on any Support plan can choose to display one, two, or all visible, editable custom ticket fields to the Web Widget contact form. Enterprise customers, or those on the Professional plan with the Productivity pack add-on, can choose any number of their custom ticket fields to display in the default contact form.

System fields, such as the Priority field, are not supported in the Web Widget. This is regardless of plan type. They appear in the default contact form (and any other ticket form), when accessed from the Help Center, but do not appear in the Web Widget.

Note: Regular expression and Date custom field type cannot be used in the Web Widget.

For general information on custom ticket fields and how they work, see Adding custom fields to your tickets and support request forms.

To display custom ticket fields in the default contact form

1. Click the Admin icon () in the sidebar, then select Channels > Widget.
2. Select the organization you want to update, then click the Customization tab.
3. In the Custom ticket fields component, click the Custom ticket fields drop-down.

   

4. Select the custom ticket field options you want to display in the contact form:
   • Essential, Team, and most Professional plan customers can select a single custom field, two custom fields, or All custom fields.
   • Enterprise plan customers, or Professional plan customers with the Productivity Pack add-on, can select any number of custom fields to display, or can select All custom fields.
5. Click Save.

Enabling ticket forms in the Web Widget

Customers on the Enterprise Support plan, or Professional plan with the Productivity Pack add-on, can use ticket forms in Web Widget.

Ticket forms allow you to customize the fields displayed in your contact form based on the type of request a customer makes. In order for this feature to work, you must have more than one ticket form created.

For general information on ticket forms and how they work, see Creating ticket forms to support multiple request types.

To enable ticket forms in your Web Widget

1. Click the Admin icon () in the sidebar, then select Channels > Widget.
2. Select the organization you want to update, then click the Customization tab.
3. In the Ticket forms component, click the toggle to on (green):

   

4. Click Save.

With ticket forms are toggled on, when a customer clicks the Leave us a message button, they're asked to select a form that matches their needs, from a list of all of your active ticket forms:

When they make a selection, the contact form displays fields specific to that ticket form.

Customizing field descriptions in the Web Widget

You can add custom ticket fields and their descriptions to the default contact form in the Web Widget. To make these appear, you must select the field from the Custom ticket fields option in the Web Widget admin settings.

However, keep in mind that system fields, such as the Priority field, are not supported in the Web Widget. This is regardless of plan type. They appear in the default contact form, and any other ticket form, when accessed from the Help Center, but do not appear in the Web Widget.

Ticket forms are only available on the Enterprise plan, and Professional plan with Productivity Pack. If you have one of these plans, you can also include custom fields and their descriptions in ticket forms. To make custom ticket fields and their descriptions appear, you must enable the Ticket forms option in the Web Widget settings.

You can create and edit ticket field descriptions from the Ticket Fields admin page. For more information about ticket fields, see About ticket fields.

To add a field description

1. Click the Admin icon () in the sidebar, then select Manage > Ticket Fields.
2. Click the name of the field that needs a description.
3. In the For end-users section, click Editable.
4. Enter a description for the field, then click Update field.

Advanced customization: Contextual ticket forms

You can craft more customized experiences for your users by limiting the forms the end-user sees based on the web page they're currently viewing, by modifying the zESettings object in the Web Widget JavaScript API. For information on working with the API, see Advanced customization of your Web Widget.

In the code for the web page you want to modify, update the zESettings object to include the ID number of the ticket form(s) you want to surface. Your Ticket Forms ID is listed in the URL in the Ticket Forms admin page.

To locate a ticket form ID number

1. Click the Admin icon () in the sidebar, then select Manage > Ticket Forms.
2. Click the name of the form you want to hide, or to use as your standalone form.
3. Take note of the form ID in the address bar:

   

Use the following examples to modify your website code.

To display a single ticket form:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      ticketForms: [
        { id: ###### }
      ]
    }
  }
};
</script>

To display two ticket forms:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      ticketForms: [
        { id: ###### }, 
        { id: ###### }
      ]
    }
  }
};
</script>

Add additional IDs to the zESettings object as needed.

Advanced customization: Pre-populating text fields

You can use new settings to pre-fill certain fields. You can use different strings for different locales, or use one string for all locales by using an asterisk (*) for the locale. This is similar to other customizable text strings like Contact Form title.

Note: This section discusses how to pre-populate system fields. For information on pre-filling user names and email addresses, see Web Widget API zE.identify.

To pre-fill a system field like 'subject' and/or 'description'
, update the zESettings object as shown below.

Example: Prefilled description text

Use the following code:

<script type="text/javascript">
zESettings = {
  webWidget: {
    contactForm: {
      fields: [
        { id: 'description', prefill: { '*': 'This is prefilled description text' } }
      ]
    }
  }
};
</script>

Example: Prefilled custom field:

Use the following code:

<script type="text/javascript">
zESettings = {
  webWidget: {
    contactForm: {
      fields: [
        { id: #####, prefill: { '*': 'Desired text' } }
      ]
    }
  }
};
</script>

In this code block, id: ##### is the custom field identifier.

You can elect to always prefill a particular field in all of your forms, or prefill it separately in specific forms.

Code example: Different text for the same field in different forms:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      ticketForms: [
       { 
         id: ###TicketFormID###, 
         fields: [
           {
              id: 'description',
              prefill: {
                '*': description
              }
            }
          ]
        },
        {
          id: ###TicketFormID###, 
          fields: [
            {
              id: 'description',
              prefill: {
                '*': 'different description'
              }
            }
          ]
        }
      ]
    }
  }
};
</script>

Advanced customization: Adding tags to tickets sent through the Web Widget from specific pages

You can add contextual tags to the tickets sent via the Web Widget. Using the zE.setting for tags, you can set specific tags on particular pages of your site. Note that these tags are public and visible to those who might be viewing the console.

Code example:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    contactForm: {
      tags: ['new_tag', 'next_new_tag']
    }
  }
};
</script>