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
• Removing the name field in the default contact form
• Making the name field in the default contact form a required field
• Using different ticket forms with the widget (Enterprise and Professional with Productivity pack add-on)

This article includes the following topics:

• Adding custom ticket fields to the default contact form
• Controlling the name field in 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 article:

• Configuring components in the Web Widget

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. For information on custom ticket fields, see Adding custom fields to your tickets and support request forms.

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.

Regular expression, Date, and multi-select custom fields cannot be used in the Web Widget.

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.

Controlling the name field in the default contact form

There are two options in your Web Widget admin settings to control the name field in the default contact form that appears in the Web Widget.

• Show name field—Use this option to remove the name field from the default contact form in the Web Widget using the Show name field option.

• Required—Use this option to make the name field a required field that users must complete before they can submit the default contact form through the Web Widget. Otherwise, the name field is labeled as optional.

  

For detailed information about these options, see Configuring components in the Web Widget.

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.

Note: If the Ticket forms toggle is off, the default contact form does not include custom fields and their descriptions in the default contact form. The default contact form will include description that states How can we help you? instead.

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>