Our themes and plugins make it easy to deliver a branded Zendesk Help Center to your customers in record time. Whether you need a ready-made template or the ability to customize pages quickly and confidently, we provide you with everything you need to get the job done.

Some theme providers attempt to provide layout and styling options through the use of theme settings alone, but this approach doesn’t come close to addressing the countless possibilities that exist. Because these themes are limited to a set of options defined by the theme author they often look the same and are difficult to customize and maintain.

What makes your themes different?

Our themes and plugins are all built on top of a powerful theming framework which provides a structured approach to customization and allows layouts to be copied between themes or from our ever-growing Pattern Library. You can think of the framework as starting with low-level settings and gradually building up to patterns which can occupy entire pages.

• Settings offer direct control over basic aspects of your theme’s appearance, including color palettes, fonts and images. Changes made through both theme settings and Sass variables are reflected in the theme’s base styles and form the foundation on which everything else in the framework is built.

  Learn about settings

• Utilities are single-purpose class names that you can use to make quick, specific changes to existing layouts. There are utilities for almost everything you could want to change, including colors, typography, positioning and sizing. They can even be combined to create entirely new designs.

  Learn about utilities

• Elements are building blocks that you can use to update or create new page layouts. They include common website and Help Center components like buttons, lists, cards, rows and columns. As with utilities, you can combine them to create new layouts or define your own using custom CSS.

  Learn about elements

• Patterns are predefined layouts, ready to copy, paste and tweak. They are often compositions of both elements and utilities and can be copied in their entirety between themes or directly from the Pattern Library. Use patterns to get ideas and significantly speed up the design and development process.

  Learn about patterns

• Plugins instantly extend the functionality of your Help Center in ways that are not possible using Zendesk’s standard templates alone. They can be used anywhere in the theme, both as a part of broader page layouts and within article content.

  Learn about plugins

This makes branding and customization faster, allows for rapid prototyping of ideas and ensures that changes are made in a consistent way based on the parameters decided by you when configuring top-level settings. There’s a practically unlimited number of ways that you can combine elements and patterns, to say nothing of the changes that you can bring about with utilities. The only constraint you’ll face is your own imagination.

Of course if one of our themes already meets your requirements, you can simply import it into Guide without making any changes at all!

Every Zendesk theme has the same folder structure, however there are some important additions for our range of themes.

Folder overview

├── assets/
├── bin/
├── scss/
├── settings/
├── templates/
├── translations/
├── manifest.json
├── script.js
└── style.css

assets/

The assets/ folder contains all custom files used by the theme, by default our framework-level JavaScript files.

bin/

The bin/ folder contains Ruby and JavaScript files responsible for compiling Sass source files into CSS and generating theme setting translations.

scss/

The scss/ folder contains the source Sass files used to compile the theme’s stylesheet.

templates/

The templates/ folder contains editable templates that define the layout of each page type, as well as the global header and footer. Each template is written using Zendesk’s full-featured templating language called Curlybars.

translations/

The translations/ folder contains translated labels and descriptions for each theme setting. If required, these can be updated using the update-translation.js file within the assets/ folder.

manifest.json

The manifest.json file contains information about your theme and is used to define the theme’s Settings panel in Guide.

script.js

The script.js file contains the compiled JavaScript for your theme. Because every theme is different, functionality provided by our plugins are added separated through the use of theme assets.

style.css

The style.css file contains the styles for your theme, compiled from the Sass source files.

Our complete theming package is just that: everything you need to create an amazing, customized Help Center.

A single purchase grants you immediate access to:

• All of our themes and plugins
• The Pattern Library
• Comprehensive documentation
• Premium support for three months

You also get lifetime access to product updates, including themes, plugins and patterns released after the date of purchase.

Each purchase includes a multibrand licence allowing you to use our products on all brands belonging to your Zendesk account.

We’re available to assist with advanced customization if required and also offer extended support for those that are interested.

Every purchase gets your immediate access to all of our themes and plugins, built on top of a powerful framework designed to make it quick and easy to create a unique and beautifully branded Help Center for your company. This includes free theme installation in your Zendesk Guide account as well as three months of premium support.

If you don’t have the time to create your own custom theme using our theming framework, we can help. Here are some of the ways that we can help you deliver an amazing customer experience:

Visit our Services page for more information.

We are experts in design, development, UX and (most importantly) Zendesk and offer a full warranty on our work. Your satisfaction is guaranteed.

If one of the themes from our ever-growing collection ticks all of the boxes for you, we offer installation with every purchase. Getting up and running with couldn’t be easier.

Agents with Guide Manager privileges can import or export a zip archive of a Help Center theme, containing templates, JavaScript, CSS, and assets.

Importing a Help Center theme

You can import a zip archive of a Help Center theme.

To import a theme into your Help Center

1. In Guide, click the Customize design icon () in the sidebar.

   The Themes page opens.

2. Click Add new theme in the upper-right corner.

3. Click Import theme file.

   

4. Find and select your theme file.

   Your theme files should be in a compressed file.

   The theme is imported and appears on your Themes page.

   You can have a maximum of 10 themes for each of your brands in Guide.

Exporting a Help Center theme

You can export any of your Help Center theme as a zip archive comprising page templates, JavaScript, CSS, and assets. This enables you to work on it locally, with your own development tools, and check it into version control. To make iterative changes to your theme, see Previewing theme changes locally.

Exporting your theme is the only way to access the manifest.json file for the theme. The manifest file enables you to customize the theme’s branding settings, including colors, fonts, and images.

To export an existing Help Center theme

1. In Guide, click the Customize design icon () in the sidebar.

   The Themes page opens.

2. Hover your mouse over the theme you want to export.

3. Click the options menu (), then select Export.

   

   The theme is downloaded to your computer in a zipped file.

You can manage your knowledge base configuration in Guide settings. You must be a Guide Manager to work with these features.

Accessing the Guide Settings page

Guide settings include options to manage your content, security, and integrations, and to deactivate your Help Center.

To configure your Guide settings

1. In Guide, click the Settings () icon in the sidebar, then select Guide settings.

   

2. Configure your settings. The following sections can be updated:

   • Managing your content settings
   • Working with security settings
   • Working with integrations settings
   • Deactivating your Help Center setting

3. Click Update.

Managing your content settings

Use the content management section to manage and moderate your public content, control spam, and configure notifications.

To manage your content

You can enable or disable these content management options:

• Anonymous voting on articles.
• The spam filter is enabled by default.
• Content moderation: sends new and edited knowledge base end-user content to a queue. You can set all content to be sent to the moderation queue, or specify certain words that will trigger the content being sent to the queue.
• Set the default sorting order for comments, when a user is looking at requests in My Requests. The options are:
  • Sort by oldest comment to newest.
  • Sort by newest comment to oldest.
• User profiles: can be public or private.

Working with security settings

Use the security section to manage content processing and sign in settings.

To work with security settings

You can enable or disable these security options:

• Display unsafe content: blocks certain content to reduce the risk of malicious code being introduced.
• Require sign in: prevents anonymous visitors to your Help Center.

Working with integrations settings

Use the integrations section to manage additional features that are available as Help Center add-ons. You can enable or disable these integration options:

• Google Analytics: includes Google Analytics tracking information for your Help Center.
• Chat: enables Zendesk Chat for your Help Center.
• Powered by Zendesk logo: displays the Zendesk log at the bottom of each Help Center page.

Deactivating your Help Center setting

You can deactivate your Help Center, preventing visitors from accessing it.

Administrators have Guide Manager privileges and agents have Guide Viewer privileges by default. Agents can be granted Guide Manager privileges as needed.

Overview of available roles

Guide supports the following user roles with different Help Center access privileges:

• Anonymous user is anybody who visits the Help Center without signing in.
• End user is somebody who has created an account and signed in to the Help Center.
• Guide Viewer is any regular Zendesk Support agent without Guide Manager privileges.
• Light agents (Support Professional add-on and Enterprise add-on) have Guide Viewer privileges for accessing content.
  • Light agents on Guide Lite and Professional cannot create or edit articles.
  • Light agents on Guide Enterprise and Legacy can create and edit articles where agents have permission.

  Permission for agents to view and edit knowledge base articles or community posts is not part of the role permissions, but is set the article level for the knowledge base and at the topic level for community.

• Guide Manager has full privileges in Guide.

For a list of specific permissions by role, see the section, Guide user privileges by role.

Setting content viewing and editing access for agents

Guide Managers have full access to the Help Center, including the ability to view all articles in the Guide admin and the ability to add, edit, and publish all content. These privileges are not part of the Guide Viewer role for agents by default, but are set at the article level for the knowledge base and at the topic level for community.

For the knowledge base, see the following articles to set agent viewing and editing access:

• Setting agent editing and publishing permissions on knowledge base articles
• Setting view permissions on articles with user segments
• Understanding agent privileges for user management permissions

For community, see the following articles to set agent viewing and editing access:

• Restricting access to Help Center community content
• Allowing agents to edit and delete articles in community topics

By default, the address of your Help Center is a Zendesk subdomain, such as “mycompany” in mycompany.zendesk.com. The host mapping feature allow you to map a subdomain of your own domain (for example, support.mycompany.com) to your default Zendesk address.

A host-mapped Help Center address has the following format:

Host mapping doesn’t affect the URL of the agent interface. It only affects the external-facing URL of Help Center.

You can’t modify your support address to direct to a specific page within your subdomain, such as mycompany.com/community/hc.

Registering a domain name

If you don’t already have a domain name, register one and add a support-related subdomain to it.

1. Purchase and register a domain name with a domain registrar.

   You can purchase and register a domain name from any domain registrar, including GoDaddy, Yahoo! Domains, Namecheap, 1&1, Netregistry, or Register.com.

2. After registering the domain name, use the registrar’s tools to add a support-related subdomain such as “support” or “help” or something along those lines. You’ll make the subdomain an alias of your default Zendesk address in the next section.

   See the Help on the registrar’s website for instructions on adding a subdomain.

Working with domain names and subdomains can be confusing because it’s something most of us rarely do. Consult your system administrator, if you have one, before proceeding.

Making the subdomain an alias of your default address

The next step is to make your chosen subdomain an alias of your default Zendesk address. An alias is simply an alternate address for a website. For example, you can make the addresses support.mycompany.com and mycompany.zendesk.com interchangeable as far as browsers are concerned.

You need to create a CNAME record on your domain registrar’s website to create the alias. If you have any concerns, consult your system administrator before proceeding.

To make your subdomain an alias of your default Zendesk address:

1. Sign in to your domain registrar’s control panel.

2. Look for the option to change DNS records.

   The option might be called something like DNS Management, Name Server Management, or Advanced Settings.

3. Locate the CNAME records for your domain.

   A CNAME record, or Canonical Name record, is a type of alias used by the Domain Name System (DNS). Among other things, a CNAME record can be used to make a subdomain an alias of an external website.

4. Do one of the following:
   • If you don’t have a CNAME record for your subdomain yet, look for an option to add a new record.
   • If you already have a CNAME record for your subdomain, look for an option to edit the record.

5. Point the CNAME record from your subdomain (shown in the Host Record field in the example below) to your Zendesk subdomain (shown in the Points To field).

   

   The UI and terminology may vary depending on your registrar, but the concepts are the same.

It may take time for changes to the DNS system to be implemented. Typically, it can take anywhere from a few hours to a day, depending on your Time To Live (TTL) settings in the registrar’s control panel. In the example above, the TTL is 14,400 seconds, or 4 hours.

Specifying a new address

After making your subdomain an alias of your default Zendesk address, you need to specify the new address in your instance of Zendesk Support. If you don’t complete this step, your new address will point to a Zendesk error page.

The instructions in this section apply if you only have one brand. If you added multiple brands, specify your addresses in Manage > Brands instead of Settings > Account. See Adding multiples brands.

1. Click the Admin icon () in the sidebar, then select Settings > Account.
2. Select the Branding tab at the top of the page.

3. Scroll down to the Host Mapping section and enter your subdomain and domain name.

   

4. Click Save Tab.

The final step is to set up hosted SSL.

You can use the standard theme that comes with Guide for your Help Center or you can customize the standard theme or create your own theme.

• The standard theme is the Copenhagen theme that comes with Guide. It’s a theme designed for best practices and mobile responsiveness. You can update the Copenhagen theme using branding and advanced settings in the Settings panel but you cannot edit the code to customize the theme. Otherwise, it will no longer be considered a standard theme.

  When you use the standard Copenhagen theme for your Help Center, it is supported by Zendesk and automatically updated when new theme features are released.

• Custom themes (Guide Professional and Enterprise) are themes that you have modified (by editing the page templates, CSS, or JavaScript) or developed from scratch. Zenplates themes are examples of custom themes.

  Custom themes are not supported by Zendesk and are not automatically updated when new theme features are released. You will continue to receive Guide features that are not theme-dependant, but you will not receive updates to your theme, as any update would overwrite your customizations.

  Zenplates themes are regularly updated to support new features and a single purchase of our theming package gives you lifetime access to these updates as well as new themes and plugins.

By default, Help Center quarantines unsafe HTML tags and attributes in articles to reduce the risk of somebody introducing malicious code. Unsafe HTML is not stripped from the articles on the server but simply not included in the HTTP responses sent to browsers. As a result, articles might not render as intended in browsers.

You can override the default setting to allow all the article HTML to be sent to a browser.

Making this change will allow potentially malicious code to be executed when users open an article in a browser.

To allow unsafe HTML in HTTP responses

1. In Guide, click the Settings icon () in the sidebar.
2. Under Security, select the Display Unsafe Content option.
3. Click Update.

Safe tags

The following list contains tags that are considered safe:

strong, em, b, i, p, code, pre, tt, samp, kbd, var, sub, sup, dfn, cite,
big, small, address, hr, br, id, div, span, h1, h2, h3, h4, h5, h6,
ul, ol, li, dl, dt, dd, abbr, acronym, a, img, blockquote,
del, ins, u, table, thead, tbody, tfoot, tr, th, td, colgroup

Even if Help Center doesn’t strip safe tags, the third-party HTML article editor used in Help Center (TinyMCE) may strip some safe tags from the HTML. For example, the editor removes <i> tags with no content, such as those used for Font Awesome icons.

Safe attributes

The following list contains attributes that are considered safe:

href, src, width, height, alt, cite, datetime, title, class, name,
xml:lang, abbr, target, border

Everything else is considered unsafe.

You can set specific community settings in Gather settings.

You must be a Guide Manager to manage the Gather settings described in this article.

1. In Guide, click the Settings () icon in the sidebar, then select Gather settings.

   

2. You can enable or disable community-wide features from this page:

   • To activate or deactivate a community, see Disabling your Help Center community.

   • To enable or disable aliases, see Enabling community aliases.

Guide managers can create moderator groups for the community so that designated agents and end-users can manage community activity. Community moderators can be any users you choose to administer community content.

You can create multiple moderator groups, if you want to set different moderator permissions for each group. If you have multiple Help Centers, any moderator groups you create apply to all your Help Centers.

Moderator groups are based on user segments for signed-in users, which are built on tags and organizations. Make sure you’ve set up a user segment that contains all the users you want to include in the moderator group before you start (see Creating user segments).

You must have Gather Professional to create moderator groups.

To create a moderator group

1. In Guide, click the User permissions () icon in the sidebar, then select Community moderators.

   You can see any moderator groups that you have already created.

2. Click Add moderator group.

   

3. Enter a moderator group name.

   For example, approve_only_moderators might be the name of the moderator group that has permission to approve posts and comments only.

4. Set the permissions by selecting the actions you want to enable for moderators in this group.

   • Mark as answered indicates that a comment has been added to the post that answers the subject of a post.
   • Pin to top moves to the top of the posts list within its topic and has a star beside it.
   • Feature post labels the post as “featured” and displays it in the featured posts component, if it’s in your theme.
   • Move post changes the location of the post to another discussion topic.
   • Hide for moderation removes a live post from the community and sends it to the content moderation queue for review. If you want to enable this action for the moderator group, ensure that you have content moderation enabled. Otherwise, this action will not be available to moderators, even if you have selected it here.
   • Approve pending content makes the content visible in the community and removes it from the content moderation queue. This action is not available for content that is pending approval in the spam queue.

5. Under Add moderators, select a user segment for the moderator group.

   You can only choose user segments for signed-in users, not staff user segments. If you need to create a new user segment, select Add new user segment.

   Matching users appear below.

   If your user segment includes agents, they will not appear in the matching list, even though they have the correct permissions. See Creating user segments for Guide user permissions.

6. Click Create group.

The moderator group is created.

When a user that has been added to the moderator group next signs in to the community, they will have additional user permissions that enable them to moderate content.

You can display snippets of translated text within your Help Center page templates. The translated variant of the text changes dynamically based on the user’s selected language, which can be updated using a language selector.

Examples of where you can use translated text include:

• A welcome message on the Home page
• A company tag line
• Service alerts and notifications
• Legal notices and disclaimers

Many of the pre-built page elements used in Help Center are already localized. For example, the element that lets users vote on an article displays “Was this article helpful?” in English and “Cet article vous a-t-il été utile?” in French.

For a list of available pre-translated strings, see the translation helper in the Help Center Templates docs.

Custom translated text uses the dynamic content feature in Support.

Specifying the language variants of the text in Support

You specify the language variants of a snippet of text on the Manage > Dynamic Content page in Zendesk Support. For instructions, see Providing multiple language support with dynamic content.

For example:

Add the content in the same language variants as the languages you support on your Help Center. If you don’t specify a variant for a language, nothing will be displayed in that language in the Help Center.

For example, suppose your Help Center supports English and French for a Canadian website. Add English and French variants of each snippet of text.

Make a note of the item name. You’ll need it for the following step. In the previous example, the placeholder is {{dc 'welcome_message'}}, so the item name is “welcome_message”.

Inserting the dynamic content in a template in Guide

Insert your text variants in Help Center templates with the dynamic content helper. When the page is requested by a web browser, the template helper inserts the appropriate text variant.

Do not include Curlybars in your dynamic content. Curlybar expressions placed inside dynamic content will not render correctly in Help Center, but will instead appear as text.

1. In Guide, click the Customize design icon () in the sidebar.

2. Click the theme you want to edit to open it.

3. Click Edit Code.

   

4. In the Templates section, click the template you want to modify.

   The page opens in the code editor.

5. Add the dynamic content in your template using the dynamic content helper. Example:

     {{dc 'welcome_message'}}
   

   If the dynamic content is missing a variant, then the default variant will be used when that locale is viewed in Help Center. Guide managers, however, will see an error message for dynamic content that does not have a variant for the current locale when they edit the Help Center theme.

6. To save your changes, click Save at the top of the sidebar.

For more information on working with templates, see Working with the page code.

Any translated article must have a parent page translated in the same language. If you add a translation for an article that does not have a corresponding translation for the section or category, users will not be able to view the article in Help Center (even though the article is published).

The page hierarchy is as follows:

• Category landing page
• Section landing page
• Article.

For example, if you add an article translated in German, the article must have a German section page. In turn, the German section page must have a German category page. The Help Center cannot display orphan articles.

When localizing your Help Center, it makes sense to start by adding localized versions of category pages, followed by section pages, followed by articles. This workflow guarantees that any new translated article has a parent section or category page that’s translated into the same language so that users can view it.

You must be a Guide Manager to add section and category translations.

To add a translated title for a section or category

1. In Guide, navigate to an existing section or category.

2. Click Edit section or Edit category in the top menu bar.

   

3. Select a language for the translation you want to add from the list at the top of the page.

   

   If you do not see a drop-down menu of languages, then you first need to enable languages for your Help Center (see Enabling languages for your Help Center).

4. Enter or paste the translated content for the name and (optionally) description.

   Keep in mind that any translated page must have a parent page translated in the same language. After you add the translation for the parent page, you can click Refresh and it will take up to three minutes before the change is registered.

   You’ll see a warning if you add a translation for a section that does not have a corresponding translation for the category. As a best practice to prevent these warnings, create the translated categories first, then go through and translate the sections.

5. Click Update translation to create the translated version of the page.

6. Repeat the steps to add more translated pages.

The following steps allow you to take advantage of the large range of custom fonts offered by Google.

1. Navigate to fonts.google.com in your browser to access the font library.

   

   If you know the type of font that you’re interested in, use the Categories filter to reduce the number of options presented.

2. Select the desired font family.

   

3. Select the font style(s) required for your Help Center.

   

4. Repeat the steps above for other font families, if required. Once the required font families and styles have been selected, click on Embed in the right-hand sidebar.

   

5. Copy the embed <link> into your document_head.hbs template.

6. Use the provided CSS rules to use your new font in CSS declarations:

   .my-element {
     font-family: 'Inter', sans-serif;
   }  
   

You can change the look-and-feel of the Help Center using theme setting controls including color pickers and font choosers. For example, you can change the logo, colors and fonts to bring your Help Center into line with your company’s branding guidelines.

In addition to updating branding with options in the Settings panel, you can control search behavior and whether or not certain page elements like comments appear.

Updating colors

By default, there are seven colors you can change in your Help Center, including:

• Primary color
• Primary text color
• Heading color
• Text color
• Link color
• Outline color
• Background color

To update your Help Center colors

1. In Guide, click the Customize design icon () in the sidebar.
2. Click the theme you want to update. The theme page opens.

3. In the Settings panel, click Colors.

   

4. Click the color box beside any of the options, then use the color selector to chose a color or manually enter the number for your color.

   The color updates in the preview window.

   Click away from the color box and the color choice is saved.

5. Repeat for other colors you want to change.

6. When you’ve finished updating your colors, click Publish.

   The changes are applied to the theme.

7. Click Back to return to the Themes page.

Updating fonts

You can change the font for headings and text by default. A list of several built-in font options are available to you.

To update your Help Center fonts

1. In Guide, click the Customize design icon () in the sidebar.
2. Click the theme you want to update. The theme page opens.
3. In the Settings panel, click Fonts.

4. To change the heading font, click the drop-down menu under Heading, then select a font for your heading.

   The font updates in the preview window.

5. To change the text font, click the drop-down menu under Text, then select a font for the text.

   The font updates in the preview window.

6. When you’ve finished updating your fonts, click Publish.

   The changes are applied to the theme.

7. Click Back to return to the Themes page.

See Using Google fonts in your theme tp learn about how to use Google Fonts with your theme instead of websafe system fonts.

Updating the logo and favicon

You can change the logo and favicon for your Help Center. The logo appears in the header for your Help Center. The favicon is the small image displayed in the browser tab and next to the URL in the browser’s address bar.

For information on uploading your own images and other branding assets to use here, see Uploading and using your own assets.

To update the logo and favicon your Help Center theme

1. In Guide, click the Customize design icon () in the sidebar.
2. Click the theme you want to update. The theme page opens.
3. In the Settings panel, click Brand.

4. If you want to change the logo, under Logo, click Replace to browse to and select an image.

   The recommended image size is 200px by 50px. For the Copenhagen theme, the recommended maximum height is 37px.

   If the width or height of the image exceeds the recommended size, the image is scaled down to keep the aspect ratio constant. The image background should be transparent or match the background color of the header.

5. If you want to change the favicon, under Favicon, click Replace to browse to and select an image.

   For best results, make sure the favicon is a square image. The image is scaled to fit the display dimensions.

6. To change back to the default image for the logo or favicon, click Revert.

7. When you’ve finished updating your logo or favicon, click Publish.

   The changes are applied to the theme.

8. Click Back to return to the Themes page.

Updating the images for your theme

The standard Copenhagen theme comes with three images that you can replace:

• Hero image, appears at the top of the home page (in the default Copenhagen Plus theme)

  

• Community hero image, appears at the top of the Community topics page (in the default Copenhagen Plus theme)

  

To update the images in your theme

1. In Guide, click the Customize design () icon in the sidebar.
2. In the Settings panel, click Images.

3. Under any of the images that appear in the Settings panel, click Replace to browse to and select an image.

   • For the Hero image the recommend size is 1600x300px.

     You can use an image that is less than 1600px wide if you are concerned about load time, but ensure that your image is at least 300px in height so that is does not appear stretched. If the image exceeds the recommended size, the image is scaled to keep the aspect ratio constant and a maximum height of 300px.

   • For the Community banner, the height should be less than 300px to avoid stretching.

     The image appears in the Settings panel. If you don’t want to use the image, you can click Revert to go back to the default image.

4. Repeat for the other images, if you want to replace them.

5. When you’ve finished updating your images, click Publish.

   The changes are applied to the theme.

6. Click Back to return to the Themes page.

You can customize your Help Center’s stylesheet and add your own custom JavaScript code. For tips, tricks and other helpful resources, refer to the following articles:

• Help Center community tips
• Help Center CSS cookbook
• Help Center JavaScript cookbook

Custom themes are not supported by Zendesk and are not automatically updated when new features are released. See The difference between standard and custom themes.

Customizing CSS or JavaScript

The following steps describe how to edit your theme’s CSS and JavaScript within Zendesk Guide.

1. In Guide, click the Customize design icon () in the sidebar.
2. Click the theme you want to edit to open it.

3. Click Edit Code.

   

4. Click script.js to modify the JavaScript or style.css to modify the CSS.

   The file opens in the code editor.

5. Add or modify the JavaScript or CSS in the code view.

6. Click Save in the top right to save your changes.

   The changes are applied to your theme.

7. To preview your changes, click Preview (see Previewing your theme in Help Center).

   

8. Make other code changes as needed, then click Save.

When you’re finished, you can close the file.

When editing theme styles you can update the style.css file directly, either through Zendesk Guide or locally using your favourite code editor. Alternatively, you can work with the Sass source files directly, which requires that you re-compile the styles once you have made your changes.

Compiling Sass

Our themes all include a simple Ruby script for handling the Sass compilation step, which can be found in the bin/ folder. The script requires both Ruby and the sassc gem to be installed. Once you have installed Ruby by following these instructions, you can install the sassc gem using the shell command gem install sassc.

You can now compile your Sass files by running the command ./bin/compile.rb from your theme directory, which will take all the .scss files inside the scss/ folder and create the style.css file that is used by Zendesk Guide.

You can upload assets, such as images and files, to any of your Help Center themes.

Uploading an asset for your theme

You can upload assets such as images and files to the Help Center. The assets are stored in a web cache in a cloud delivery network (CDN). Web caches reduce bandwidth requirements and server load, and improve response times.

There are a number of allowable file types for themes (see Allowable file types for theme assets).

To upload your own theme assets

1. In Guide, click the Customize design icon () in the sidebar.

2. Click Customize on the theme you want to edit.

3. Click Edit code.

   

4. In the Assets section, click Add asset, then browse to select your file.

   

   Theme asset names must be unique and cannot be more than 50 characters. Asset names can contain any of the following: letters, numbers, dot, minus, plus, underscore, and dash. Asset names are not case sensitive, so you cannot have an asset named asset.jpg and Asset.jpg.

   The asset file is added to your list of asset files.

Allowable file types for theme assets

The following table shows the file types that are allowed as theme assets. The allowable files types for assets are limited to the file types used in the theming of a Help Center.

Rich content files types, such as Microsoft PowerPoint, Microsoft Word and PDFs, can be article attachments but cannot be theme assets.

Using uploaded assets in the theme’s code

You can reference an uploaded asset in the theme’s style.css file or in its templates. In style.css, you use asset path variables provided by Guide. In templates, you use the Curlybars asset helper.

Using asset variables and helpers in your code lets you easily replace the assets in the theme without editing the theme code. See Replacing an asset in your theme.

You can’t use the path variables or the helper in the theme’s script.js file.

To use an uploaded asset in your theme code

1. In Guide, click the Customize design icon () in the sidebar.

2. Click Customize on the theme you want to edit.

3. Click Edit code.

4. In the Assets section, click the asset file you want to use.

   Various expressions for the asset appear:

   

5. Click Copy to copy the asset expression you need in the Clipboard.
6. Paste the asset expression in your theme code.

Examples

style.css

.class-name {
  background: url($assets-backpack2-jpeg);
}

The value assets-backpack2-jpeg is a variable that contains the relative path to the asset.

.hbs files

In html markup:

<img src="{{asset 'backpack2.jpeg'}}">

In a style tag:

<style>
  .class-name {
    background: url("{{asset 'backpack2.jpeg'}}");
  }
</style>

In a script tag:

<script>
  var assetsBackpack2 = "{{asset 'backpack2.jpeg'}}";
</script>

While you can insert the asset helper in a script tag in a template, you can’t use it in the script.js file.

For more information on editing your theme code, see Customizing your Help Center theme.

Replacing an asset in your theme

Using asset variables and helpers as described in Using uploaded assets in the theme’s code above lets you replace an asset in the theme dynamically without editing the theme code. You can update the theme just by selecting a new asset file on your system.

To replace an asset

1. In Guide, click the Customize design icon () in the sidebar.

2. Click Customize on the theme you want to edit.

3. Click Edit code.

4. In the Assets section, click the asset file you want to replace.

5. Click the options menu on the upper-right side, then select Replace.

   

6. Select a new asset on your system.

   Once uploaded, the theme is updated dynamically by any variable or helper that references the asset. The change is immediate.

   The asset is not replaced if you used the full URL of the asset in the HTML source of published Help Center pages. The link to the asset will break because replacing an asset changes the asset’s published URL. As a result, avoid using the published asset URL in a theme, a page template, or an external web page.

Deleting a theme asset

You can easily delete any theme asset you’re no longer using in your theme.

To delete a theme asset

1. In Guide, click the Customize design icon () in the sidebar.

2. Click Customize on the theme you want to edit.

3. Click Edit code.

   

4. In the Assets section, click the asset file you want to delete.

5. Click the options menu on the upper-right side, then select Delete asset.

   

6. Confirm that you want to delete the asset.

   The asset is removed from your assets list.

When Zendesk’s Curlybars templating language can’t generate the desired HTML, our JavaScript-based micro-templating system steps in.

A common use case for micro-templating is the creation of a category list that’s present on all pages in the Help Center. This is not possible out-of-the-box because the required template property, in this case an array of category objects, is only available on the Home page.

We offer a convenient way of fetching properties for use in JavaScript, so your imagination becomes the only constraint when creating new layouts and features within Zendesk Guide.

Usage

The micro-templating system requires a template string to generate HTML, which can be provided as a literal string of text or retrieved from a <script> element.

If a <script> element is used, it should have an ID in the format tmpl-{template_name}. For example, the custom-articles-list template below renders a collection of articles:

<script type="text/html" id="tmpl-custom-articles-list">
  <% if (articles.length) { %>
    <ul class="list-unstyled">
      <% articles.forEach(function(article) { %>
        <li class="list-item" id="<%= article.id %>">
          <a href="<%= article.html_url %>">
            <%= article.name %>
          </a>
        </li>
      <% }); %>
    </ul>
  <% } %>
</script>

Micro-templates are similar to the Curlybars templates used by Zendesk.

1. Use <% … %> to execute custom JavaScript code. This is often used to apply conditional logic or manipulate data.
2. Use <%= … %> to print values to the screen. If the value should be HTML-escaped, use <%- … %>.

Micro-templates can be placed in any of the Zendesk Curlybars page templates and, as a result, you can reference all objects available on the page in the way that you normally would.

Via data attributes and plugins

Plugins that are responsible for rendering markup have a template option that allows a custom template to be used instead of the default. For example, when using the Articles List plugin to render a list of articles you can specify a custom template (my-custom-template) using data attributes:

<div data-element="articles-list" data-template="custom-articles-list"></div>

Alternatively, the plugin can be initialized (and options set) using JavaScript:

<div id="articles-list"></div>

<script type="text/javascript">
  ready(function() {
    var articlesList = document.getElementById('articles-list');
    if (articlesList) {
      new Articles(articlesList, {
        template: 'custom-articles-list',
        templateData: { ... }
      });
    }
  });
</script>

All examples above require that a micro-templates exists on the page with an ID of tmpl-{template_name}:

<script type="text/html" id="tmpl-custom-articles-list'">
  ...
</script>

Via JavaScript

Micro-templates can be rendered using the renderTemplate() utility method.

var articlesList = document.getElementById('articles-list');
var data = {
  "articles": [ ... ] 
};

Util.renderTemplate(articlesList, 'custom-articles-list', data);

Guide templating, also known as the Templating API, is responsible for rendering the Help Center theme packages. This contains the Curlybars templating language that is used in the template files, CSS and JS files, and the manifest file.

To learn more about Guide themes, see Customizing your Help Center theme and the Help Center Templates developer documentation.

About Guide templating versions

Version 2 of the Templating API was released on February 24, 2020 and applies to the Copenhagen theme and any new theme releases. You can find out which version of the framework from the Customize design icon () in Guide (see Finding out the templating version).

All Zenplates themes are built using the latest version of the Templating API which removes jQuery entirely to ensure themes remain fast and nimble. All custom functionality in our themes is written in vanilla JavaScript however if to use jQuery you can import the jQuery library.

For a full list of changes in version 2, refer to the online documentation.

Finding out the templating version

You can see the templating version from the Edit code view in your theme, or in the manifest file.

To check the templating version

1. In Guide, click the Customize design icon () in the sidebar.
2. Click the theme you want to see.
3. Click Edit code.

4. Under the preview option, you’ll see the templating version number, for example, Templating API v1.

   

   This version number corresponds with the api_version field in the manifest file.

The HTML for the Help Center is contained in editable templates that define the layout of each page type, as well as the global header and footer. You can also use a full-featured templating language called Curlybars to access Help Center data and manipulate content in page templates.

On Guide Enterprise, you can create additional page templates for articles, sections, and categories if you need multiple versions of those templates.

You can customize the template of any of the following page types or elements:

• Article page (article_page.hbs): the individual article pages in the knowledge base
• Category page (category_page.hbs): landing pages
• Community post list page (community_post_list_page.hbs)
• Community post page (community_post_page.hbs)
• Community topic list page (community_topic_list_page.hbs)
• Community topic page (community_topic_page.hbs)
• Contributions page (contributions_page.hbs): the lists of posts, community comments, and article comments by an end-user
• Document head (document_head.hbs): the document’s head tag
• Error page (error_page.hbs): the message displayed when a user lands on a non-existent page
• Footer (footer.hbs): the bars appearing at the bottom of all Help Center pages
• Header (header.hbs): the bars appearing at the top of all Help Center pages
• Home page (home_page.hbs): the top-level landing page for your Help Center
• New community post page (new_community_post_page.hbs)
• New request page (new_request_page.hbs): the request or ticket submission form
• Request page (request_page.hbs): the individual request or ticket pages
• Requests page (requests_page.hbs): the lists of requests or tickets assigned to a user or that a user is CC’d on
• Search results (search_results.hbs): the search results display format
• Section page (section_page.hbs): landing pages
• Following page (subscriptions_page.hbs): the list of categories, sections, and articles a user is following
• User profile page (user_profile_page.hbs)

When you use the Theme Editor to edit the page templates, CSS, or JavaScript for a standard theme, or when you develop your own theme, it is saved as a custom theme. Custom themes are not supported by Zendesk and are not automatically updated when new features are released. See About standard themes and custom themes in Help Center.

To edit the page templates

1. In Guide, click the Customize design icon () in the sidebar.

2. Click the theme you want to edit to open it.

3. Click Edit code.

   

4. In the Templates section, click the template you want to modify.

   The page opens in the code editor.

5. Use the code view to edit the template.

   You can add, remove, or reorder any the following:

   • Template expressions to display and manipulate content in your pages

   For example, the breadcrumbs template helper {{breadcrumbs}} displays a breadcrumb navigation element on a page. For a detailed guide on template expressions, see Help Center Templates.

   • Dynamic content placeholders (see Adding translated text)
   • Embeddable widgets created by third parties (such as the Twitter search widget)
   • HTML markup

6. Click Save in the top right corner to save your changes.

   The changes are applied to every page in your theme that is based on the template you modified.

7. To preview your changes, click Preview (see Previewing your theme in Help Center).

   

8. Make other code changes as needed, then click Save.

   When you’re finished editing the page template, you can close it.

The properties you choose in the Settings panel or set in your manifest file for colors, fonts, and theme images are stored in variables. You can use these variables in the theme’s style.css file. You can also reference the variables using Curlybars expressions in HTML page templates.

The variables are useful if you want to specify the same value in several places and update it quickly. Updating the property updates it everywhere the variable is used. You can change the names and labels, delete variables, or add your own (see the Settings manifest reference).

For a complete list of the default settings available in our themes, refer to our online documentation.

Examples using variables in CSS

The properties you set for colors, fonts, and theme images are stored in variables that you can use in your theme’s style.css file.

For example, you can use some of the default variables in CSS with the following syntax:

• $primary_color
• $primary_inverse_color
• $heading_font
• $text_font

In the CSS file, you assign a variable to a CSS property the same way you would assign a normal value. For example:

.button {
  label-color: $text_font;
}

You can also use single curly brackets to embed the helper in a CSS expression, as follows:

max-width: #{$search_width}px

Examples using variables in Curlybars in HTML

The properties you set for colors, fonts, and theme images are stored in variables that you can reference with Curlybars expressions in HTML page templates.

The variables become properties of the settings object in Curlybars. As with any Curlybars object, you can use double curly brackets and dot notation to insert an property in a page template.

For example:

• {{settings.color_1}} is the HEX value of a color. For example: #FF00FF
• {{{settings.font_1}} is the font stack. For example, system is defined as: ‘-apple-system, BlinkMacSystemFont, ‘Segoe UI’, Helvetica, Arial, sans-serif”
• {{settings.homepage_background_image}} is the path to the file stored in this field. For example: p8.zdassets.com/theme_assets/…
• {{settings.range_input}} is the value of the range input.

The settings object can be used as input to any helper. For example:

{{is settings.enabled}} ... {{/is}}

By default, there is one page template each for article, section, and category in a theme. You can create up to ten additional page templates each for articles, sections, and categories.

This means that you can create alternate versions of templates to use for your articles, sections, and categories. You can apply or change the page template when you create or edit an article, section, or category.

You must have Guide Enterprise and you must be a Guide Manager to create multiple templates.

Adding multiple templates using the theme editor

You can create additional page templates for articles, sections, and categories using the theme editor in Guide. If you prefer working on your themes locally, you can also add templates to your exported themes.

To add an article, section, or category template using the theme editor

1. In Guide, click the Customize design icon () in the sidebar.

   Your themes appear on the Themes page.

2. Hover your mouse over the theme you want to edit, then click View theme.

3. Click Edit Code.

   

4. Scroll to the bottom of your templates list, then click Add new template.

   

5. Under Template for, select the type of template you’d like to create.

   You can create article, section, and category templates only. You can create up ten additional templates for each type.

   

6. Enter a Template name.

7. Under Start from, select an existing template to copy and use as a starting point.

   You can select blank template if you don’t want to start from another template.

8. Click Create template.

   The new template opens for you.

9. Edit your template and click Save as you go.

10. To preview your template, click Preview, then click Templates at the top of the preview and select the template you want to preview.

    

    For more information, see Previewing your theme while editing theme code.

When you are ready, you can apply your template to a new article or new category or section. You can also change the template on an existing article, section, or category.

Adding multiple templates in exported themes

If you export and work on themes locally, you can add multiple templates to the themes. The workflow consists of creating a predefined folder in a theme’s templates folder, then adding .hbs template files to the folder.

To learn more about working on themes locally, see Working on a theme locally.

To add a template to an exported theme

1. Depending on the type of template you want to add (article, section, or category), create any of the following folders in the templates folder of the exported theme:

   • article_pages
   • section_pages
   • category_pages

   As in the Guide theme editor, you can only create article, section, and category templates.

2. Add an .hbs template file in the new folder.

   You can name the file anything you want. The name must be 25 characters or less, and snake_case.

   

   To save time, copy an existing .hbs file into the folder to use as a starting point for the new template.

3. Edit and save the template.
4. If you need to add more templates of the same type, add them to the same folder.
5. When you’re done, zip the theme and import it into Guide.

Use Guide to preview the new template.

When you are ready, you can apply your template to a new article or new category or section. You can also change the template on an existing article, section, or category.

In a Guide theme, there is one page template each for article, section, and category by default. On Guide Enterprise, Guide managers can create additional templates for article, sections, and categories. If your live theme has multiple templates for these template types, you can change the template for an article, section, or category at any time.

Agents can change the template on any article they have permission to edit. You must be a Guide Manager to change the template for a section or category.

Changing the template for an article

If you have multiple article templates in your live theme, you apply a template when you create a new article. You can change the template on an existing article at any time.

Agents can change the template on any article they have permission to edit.

To change the template for an article

1. In Help Center, navigate to the article you want to edit, then click Edit article in the top menu bar.

   

   Alternatively, in Guide, click the Manage articles () icon in the sidebar, then select an article from an article list to open it in edit mode.

2. In the sidebar, click Article settings.

3. Click the Template menu, then select a template.

   You might have to scroll down to see this option.

   

4. Click Save.

   The live article is updated with the new template. You cannot preview this change in the article editor.

Changing the template for a category or section

If you have multiple category or section templates in your live theme, you apply a template when you create a new category or section. You can change the template on an existing category or section at any time.

You must be a Guide Manager to change the template for a section or category.

To change the template for a category or section

1. In Help Center, navigate to the category or section you want to edit, then click Edit category or Edit section in the top menu bar.

   

   Alternatively, in Guide Admin, click the Arrange content () icon in the sidebar, then click the title of the category or section to open it in edit mode.

2. In the sidebar, click the Template menu, then select a template.

   

3. Click Update.

   The live category or section is updated with the new template.

Instead of bloating our themes with extra font files containing icons that you may or may not use, we inline SVG icons which offer better page load performance and improved accessibility over font-based icon systems. Zendesk’s default Copenhagen theme recently made the same change with the release of the new theming API.

Our Icons page contains an excellent starter set of icons and there are many collections (and thousands of icons) available online for free like Bootstrap Icons, Heroicons and Icons8.

For more information about the differences between font-based and inline SVG icons, refer to this article.

Usage

Use .svg-icon with an inline SVG icon to make it scale in relation to surrounding text.

<h1 class="my-4">Heading 1 <svg class="svg-icon">...</svg></h1>
<h2 class="my-4">Heading 2 <svg class="svg-icon">...</svg></h2>
<h3 class="my-4">Heading 3 <svg class="svg-icon">...</svg></h3>
<p>A paragraph of text <svg class="svg-icon">...</svg></p>

A variety of different icons are included within each of our themes, which you can mix-and-match.

Some examples of commonly used SVG icons include:

Sizes

Use font size or sizing utilities can be used to control how large an icon appears.

<svg class="svg-icon text-red-500"></svg>
<svg class="svg-icon text-red-500 font-size-2xl"></svg>
<svg class="svg-icon text-red-500 h-6 w-6"></svg>

Colors

Use .fill-current or .stroke-current to set the fill or stroke color of the SVG to the current text color. Text color utilities can then be used to control the color of an icon.

<svg class="svg-icon font-size-2xl fill-current p-2 text-red-500"></svg>
<svg class="svg-icon font-size-2xl fill-current p-2 text-green-500"></svg>
<svg class="svg-icon font-size-2xl fill-current p-2 text-orange-500"></svg>
<svg class="svg-icon font-size-2xl fill-current p-2 text-gray-600"></svg>

A great way to highlight important aspects of your content is to use callouts. These are typically expressed as tips or notes, though the specific language used should be consistent with your company’s brand.

<p class="note">
  This is an example of a standard note available in all themes. You can apply this 
  style to any content by simply applying the <code>.note</code> class name to a 
  paragraph or container element.
</p>

Warning styles can help draw visitor attention to important information:

<p class="warning">
  This is an example of a standard warning available in all themes. You can apply this 
  style to any content by simply applying the <code>.warning</code> class name to a 
  paragraph or container element.
</p>

Different styles can be created using custom CSS or utilities.

<div class="border-left border-4 bg-orange-100 text-orange-600 border-orange-500 px-5 py-1 mb-4">
  <h4 class="text-inherit text-orange-500 mt-4 mb-2">
    Caution
  </h4>
  <p>
    This is an example of a custom notification using utilities. You can easily 
    customize this to suit the look-and-feel of your theme or create your own.
  </p>
</div>

Each style can be used with our set of font and SVG icons to add extra visual appeal.

Boxes

Information that’s related to the main content of the page but more of an aside can be displayed within a box. As with all of our patterns, you can customize the appearance to meet your requirements using our utilities (for example, box shadows).

<div class="px-6 py-4 border border-radius shadow-xs">
  <h3>
    In summary
  </h3>
  <ul class="list-check my-5">
    <li class="list-item">This was an important point</li>
    <li class="list-item">As was this</li>
    <li class="list-item">And even this</li>
    <li class="list-item">The final and most important point</li>
  </ul>
</div>

The <code> and <pre> elements are for displaying inline and multiline blocks of code.

Usage

Use the <code> element for inline code snippets.

<p>The <code>push()</code> method adds one or more elements to the end of an array and returns the new length of the array.</p>

Use the <pre> element for multiple lines of code.

  L          TE
    A       A
      C    V
       R A
       DOU
       LOU
      REUSE
      QUE TU
      PORTES
    ET QUI T'
    ORNE O CI
     VILISÉ
    OTE-  TU VEUX
     LA    BIEN
    SI      RESPI
            RER       - Apollinaire

<pre>
  L          TE
    A       A
      C    V
       R A
       DOU
       LOU
      REUSE
      QUE TU
      PORTES
    ET QUI T'
    ORNE O CI
     VILISÉ
    OTE-  TU VEUX
     LA    BIEN
    SI      RESPI
            RER       - Apollinaire
</pre>

Use <kbd> for input that is typically entered via keyboard.

<p>To edit settings, press <kbd>ctrl</kbd> + <kbd>s</kbd></p>

Use the <figure> element to display self-contained content, like illustrations, images, photos or code. For image-specific styles, refer to the Images page.

Usage

Use the <figcaption> element to display a caption for a given <figure>.

<figure>
  <img class="img-fluid" src="..." alt="...">
  <figcaption class="mt-4">This is a caption for the image.</figcaption>
</figure>

Use text align utilities to align the caption relative to the image.

<figure>
  <img class="img-fluid" src="..." alt="...">
  <figcaption class="mt-4 text-right">This is a caption for the image.</figcaption>
</figure>

Image styles

Images often play an important role in content, providing useful information and helping to illustrate points. Images can be displayed within <figure> elements and given an optional caption using the <figcaption> element.

Using a few simple class names, you can change the alignment of your images and even have them extend slightly beyond the content area for added effect.

Use .float-left to have an image float to the left of the content. Responsive variants allow you to control the float based on screen size.

There should be some space above, below and on the appropriate side of the image to ensure separation between the image and surrounding text. This will make the page look better and improve readability.

Margin utilities allow you to apply spacing around the image and reposition the element on larger screen sizes. Text alignment utilities can be used to control the alignment of the caption.

The left-aligned example uses .my-5 and .lg:mr-6 to apply margin around the entire element and lg:-ml-6 to shift the image further to the left on large screen sizes.

Use .float-right to achieve a similar (but opposite) effect. Consider using other utilities, for example borders and background colors, to add further interest to your images or apply your own styles to figures or images within the content area (.content) using custom CSS.

When floating elements it may occasionally be necessary to use .clearfix to ensure content remains within the content area.

Use .list-unstyled to remove the default styling from <ol> and <ul> elements.

<ul class="list-unstyled">
  <li>List item</li>
  <li>List item</li>
  <li>List item</li>
</ul>

Use .list-item to add additional space around each list item.

<ul class="list-unstyled">
  <li class="list-item">List item</li>
  <li class="list-item">List item</li>
  <li class="list-item">List item</li>
</ul>

<ul>
  <li class="list-item">Lorem ipsum dolor sit amet, adipiscing elit.</li>
  <li class="list-item">Nulla vitae elit libero, a pharetra augue.
    <ul>
      <li class="list-item">Donec id elit non mi porta gravida at eget metus.</li>
      <li class="list-item">Quisque fringilla elit quis purus consectetur.</li>
    </ul>
  </li>
</ul>

List style utilities provide additional control over the look-and-feel of lists.

Numbered list

Use .list-number to apply a custom numbered style to a list.

<ol class="list-number">
  <li class="list-item">List item</li>
  <li class="list-item">List item</li>
  <li class="list-item">List item</li>
</ol>

Check list

Use .list-check to apply a custom checklist style to a list.

<ul class="list-check">
  <li class="list-item">List item</li>
  <li class="list-item">List item</li>
  <li class="list-item">List item</li>
</ul>

Divider list

Use .divider-list to present list items in a horizontal list separated by a divider.

<ul class="list-divider">
  <li>List item</li>
  <li>List item</li>
  <li>List item</li>
</ul>

The data-divider attribute allows you to override the divider applied before a given list item:

<ul class="list-divider">
  <li>List item</li>
  <li data-divider=">">List item</li>
  <li data-divider="/">List item</li>
</ul>

We use this element in our themes to present call-to-actions, menus and lists of articles.

Blockquotes

Use <blockquote> for quoting blocks of content from another source within your document.

<blockquote class="font-size-lg">
  <p>
    Success is not defined by the ability to have no complaints, it is defined by the ability to deal with them.
  </p>
  <footer class="text-gray-500">
    Mikkel Svane in <cite title="Source Title">Startupland</cite>
  </footer>
</blockquote>

Pull-quotes

You can also emphasize parts of your content using utilities or your own custom elements. The following paragraphs help prove this point by providing a body of text in which a pull-quote can be placed.

“Your most unhappy customers are your greatest source of learning.”

You’ll notice that the quote itself is made larger and bolder using typography utilities. Space is added around the element and, on large screens, shifted left using margin utilities.

There’s really no limit to what you can do with our utilities. Of course you could create a right-aligned version that looked much the same, or create your own unique versions.

Draw inspiration from what you see online, get excited and get creating!

Tabs are a navigation element that allow users to easily access different parts of a page, or even other parts of the Help Center. They are commonly used on the Web and, as a result, intuitive.

Use tabs to group content, create relationships between related information and as a tool to save space.

Usage

Creating tabs within your articles is easy:

1. When editing an existing article, create a list (<ul> or <ol> element) and click the Source Code () button on the editor toolbar to view the source code of the page.
2. Add the data-element="tabs" attribute to the list element.
3. Add optional tab titles to each list item using the data-title attribute.

<ul data-element="tabs">
  <li data-title="The first tab">
    <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed, euismod in, nibh. Quisque volutpat condimentum velit. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nam nec ante. Sed lacinia, urna non tincidunt mattis, tortor neque adipiscing diam, a cursus ipsum ante quis turpis.</p>
  </li>
  <li data-title="The second tab">
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
  </li>
  <li data-title="The third tab">
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer congue justo a metus bibendum dapibus. In imperdiet interdum tincidunt. Nam odio dolor, hendrerit vel eros non, viverra pellentesque tellus. Proin ac elit in leo faucibus gravida. Donec ut neque non augue porttitor mollis a quis eros.</p>
  </li>
</ul>

Toggles and accordions are a common element in web design. They allow for progressive disclosure — the ability to highlight important sections of content and allow visitors to reveal additional details with a click.

Accordions look and behave exactly like toggles except for the fact that only one within a given section can be open at a time.

Usage

Creating toggles within your articles is easy:

1. When editing an existing article, create a list (<ul> or <ol> element) and click the Source Code () button on the editor toolbar to view the source code of the page.
2. Add the data-element="togggles" attribute to the list element.
3. Add optional tab titles to each list item using the data-title attribute.
4. To have the group of toggles behave as an accordion, use the data-accordion="true" attribute.

<ul data-element="toggles" data-accordion="true">
  <li data-title="The first toggles">
    <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed, euismod in, nibh. Quisque volutpat condimentum velit. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nam nec ante. Sed lacinia, urna non tincidunt mattis, tortor neque adipiscing diam, a cursus ipsum ante quis turpis.</p>
  </li>
  <li data-title="The second toggles">
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
  </li>
  <li data-title="The third toggles">
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer congue justo a metus bibendum dapibus. In imperdiet interdum tincidunt. Nam odio dolor, hendrerit vel eros non, viverra pellentesque tellus. Proin ac elit in leo faucibus gravida. Donec ut neque non augue porttitor mollis a quis eros.</p>
  </li>
</ul>

Your customers can provide feedback about their support experience by rating their solved tickets. When you enable CSAT (customer satisfaction ratings), end-users receive an email 24 hours after the ticket has been set to solved that asks them to briefly evaluate their experience, as shown here:

The survey is designed to maximize the response rate by being quick and simple while also gathering the essential data: a positive or negative rating. Customers can also provide a comment if they want. You can view your overall score and individual ratings in the Customer Satisfaction dashboard (see Viewing your Customer Satisfaction score and ratings).

Customer satisfaction rating is available with Support Professional and Enterprise plans. You must be an administrator to enable customer satisfaction ratings.

Understanding the end-user experience

End-users don’t have to be logged in to rate their tickets. Clicking a response link in the email opens a URL to the ticket and prompts the end-user to rate the ticket and add a comment if they’d like. In this example, the end-user clicked the ‘Good, I’m satisfied’ link so the Good button is shaded green to indicate that it is the selected rating. A comment can be added and the rating can be changed.

If you have satisfaction reasons enabled, end-users who select ‘Bad, I’m unsatisfied’ are presented with a drop-down menu of possible reasons for their negative response.

Selecting a response is optional, and can be skipped. For information on this feature, see Working with satisfaction reasons.

In Help Center, the rating prompt appears on tickets for which the Ticket Satisfaction is set to Offered by an automation or trigger. For more information, see Understanding how the survey request is sent.

End-users can change their rating by clicking the emailed link again or by accessing the ticket through the My activities page in Help Center, then resubmitting their response. Ratings can be changed until the ticket is closed. See Tracking your support requests for information on viewing your tickets in Help Center.

Dylan Dimico shares some tips and tricks on changing your bad satisfaction ratings to good. Check it out in Changing bad satisfaction ratings to good.

The following rules apply to end-users when using satisfaction rating:

• End-users cannot opt-out of receiving survey requests.
• Satisfaction rating is per ticket, not per customer. End-users receive a survey request for each of their tickets that are solved.
• Once a ticket is set to “Closed” status, the temporary URL will no longer work. It will re-direct the user to a generic page.

When and how end-users are asked for a satisfaction rating through email is customizable. You can set a time other than the default 24 hours later for to send the email. You can also add the survey request in the email that customers receive when a an agent marks a ticket as solved instead. You can also use business rules to be more selective about (include or exclude) which tickets generate the survey request. If you send a satisfaction survey before the ticket is solved, end users need to sign in to access it.

Understanding how the survey request is sent

When you enable customer satisfaction rating (see Enabling customer satisfaction rating), a system-generated automation called Request customer satisfaction rating is added to Zendesk Support. This automation sends the survey email to the ticket requester 24 hours after the ticket is solved. You can of course customize this.

The email body in the automation uses a placeholder called {{satisfaction.rating_section}} to insert the survey question into the message, as shown here:

Hello {{ticket.requester.name}},

We'd love to hear what you think of our customer service. Please take a moment to answer one simple question below:

{{satisfaction.rating_section}}

Here's a reminder of what your ticket was about: {ticket.comments_formatted}}

When customers receive the email, they simply click either the Good or Bad links and follow the steps described above.

For more details about the automation, see Customer satisfaction rating automation.

As noted above, the survey is sent when the ticket is set to Solved. It’s possible to use a different status in the automation, such as Pending, but the ticket would have had to be set to Solved at least once before.

About the Request Customer Satisfaction Rating automation

The customer satisfaction rating automation, Request customer satisfaction rating (System Automation), sends the survey request email 24 hours after a ticket has been solved.

Remember that the condition statement is Hours since solved is 24 not Hours since solved greater than 24. This means that when you first enable customer satisfaction rating, none of the tickets that have been solved for more than 24 hours will generate a survey email. You can change this of course.

You might consider changing the number of hours after solved that you send out surveys to get more responses. Check out this blog post about maximizing survey responses.

You’ll notice that there’s a Ticket Satisfaction condition as well. This condition has the following values:

• Unoffered means that the survey has not previously been sent
• Offered means that the survey has already been sent
• Bad is the requester’s negative rating
• Bad with comment is the requester’s negative rating with their comment
• Good is the requester’s positive rating
• Good with comment is the requester’s positive rating with their comment

The unoffered value is used here because we only want to send the survey for tickets that have not already been rated.

The automation actions send the survey request email to the requester.

The {{satisfaction.rating_section}} placeholder contains the rating question and answer links. You can modify the surrounding message as needed. And as always, a canceling action is used to complete the automation; ticket satisfaction is set to offered to requester.

This automation can be modified to exclude tickets using many different criterion. For example, you might not want surveys sent for tickets assigned to a certain group or from a certain organization or for tickets containing certain tags.

Understanding how agents receive the customer satisfaction rating feedback

The results of customer satisfaction surveys for agents are shown in the agent’s dashboard and in a view called Rated tickets from the last 7 days.

Agents see, in their dashboard (when they click the Home icon () in the sidebar), the number of good and bad tickets for the last week and the overall satisfaction rating for the agent and all of the agents in Zendesk Support over the last 60 days (including the current day).

The calculation of the overall satisfaction rating uses the following simple formula:

This means that the score is an average of the total positive ratings from the past 60 days. An agent with a score of 90% means that over the past 60 days, 90% of the ratings they received were positive.

Agents, groups, and the account all have scores. The overall account score (in the example above, 95%) is the average for all agents in Zendesk Support. The two ratings provide feedback about individual performance and the average performance of all agents.

An overall rating score will not be shown until 30 tickets are rated. This applies at the agent, group, and account levels. This means that an agent needs 30 ratings, a group (all agents within the group) needs 30 ratings, and the account (all the agents in your Zendesk account) needs 30 ratings.

The view (Rated tickets from the last 7 days) gives you a quick overview of the rating activity, with a Satisfaction column containing both Good and Bad ratings. You can clone and modify this view or create your own. This view is inactivate by default.

The following rules apply to agents when using customer satisfaction rating:

• Agents cannot rate tickets.
• All agents see their ratings in their dashboard. This feature is enabled at the account level and applies to all agents in your Zendesk account. You cannot exclude individual agents from receiving ratings on the tickets they are assigned to.

Additionally, ratings cannot be moderated. All ratings are shown.

You can display satisfaction ratings in your Help Center. This lets you show quick statistics based on your last 100 satisfaction ratings. The following data is shown:

• Number of positive ratings
• Number of negative ratings
• Overall score (percentage of good ratings)

The numbers are based on your last 100 ratings, so it’s a sliding window that is recalculated every time you receive a rating. The appearance and wording is customizable.

You must have Guide Professional and Support Professional or Enterprise to display satisfaction ratings and score in your Help Center.

Getting the code for the ratings box

You add the ratings box by pasting a code snippet into the HTML of a page or template. You must be an admin to get the code.

1. Click the Admin icon () in the sidebar, then select Customers.
2. Click the Satisfaction tab.

3. Make sure that Allow customers to rate tickets is selected and that you have at least 100 ratings. If you don’t have at least 100 ratings, you’ll see the following message. In that case you have to wait until you get more ratings to use the ratings box.

   

4. Select Allow me to display public satisfaction statistics.

5. Click Save Tab.

   The page updates with more information, including statistics based on your last 100 customer satisfaction ratings.

6. Under How do I use it, copy all the HTML code in the box. You’ll only see this HTML code if you if have 100 or more satisfaction ratings.

Adding the ratings box in the Help Center

Guide Managers can add the ratings box to articles or to the home page of the Help Center.

To add the ratings box to the home page of your Help Center

1. In Guide, click the Customize design icon ( in the sidebar.
2. Click the theme you want to edit to open it.

3. Click Edit Code.

   

4. In the Templates section, open the home page template.
5. Paste the code for the ratings box in the template.
6. Click Save.
7. Click Preview to preview the effect of your changes on the page.

To add the ratings box to an article in the Help Center

1. In Guide, click the Settings icon () in the sidebar.

2. Ensure the Display Unsafe Content setting is enabled.

   In this case, you want to allow unsafe content like script tags.

3. Back in the Help Center, navigate to the article where you want the ratings box to appear.
4. Click Edit article.
5. Switch to the HTML editor by clicking Source code button on the editor’s toolbar.
6. Paste the code for the ratings box in the page and click Save.

The ratings box appears wherever you paste the code. If you want to customize the wording, the CSS, or place the box in a specific element on the page, see Customizing the ratings box below.

Customizing the ratings box

You can customize the satisfaction ratings box by changing the wording, changing the look, or setting where it appears on the page.

Customizing the wording

If you don’t like the default wording that appears under the three numbers in the ratings box, you can change it. In the ratings box code, look for the following values:

Satisfaction.show({
    strings: {
      goodRatings:      "Said good",
      badRatings:       "Weren't so sure",
      score:            "Overall happiness",
      zendeskPlug:      "Powered by <a href=\"http://www.zendesk.com/\">Zendesk</a>"
    }
});

You can edit the values in quotes.

Customizing the look

The code you pasted into your HTML imports a CSS stylesheet:

@import url(https://support.zendesk.com/stylesheets/public_satisfaction.css);

If you want to customize the look of the ratings box, you an add your own CSS to the page where you put the ratings box, overwriting the CSS defined in the Zendesk stylesheet.

One of Zendesk Support’s most popular features is the built-in customer satisfaction survey. Customer satisfaction allows you to track how well your agents and customer service organization as a whole are performing on a ticket by ticket basis.

Enabling the customer satisfaction feature

To enable customer satisfaction surveys, click the Admin icon () in the sidebar, then select Settings > Customers > Satisfaction.

When you enable customer satisfaction, a pre-built automation is automatically created for you. To see this automation:

1. Click the Admin icon () in the sidebar
2. Select Business Rules > Automations
3. Open Request customer satisfaction rating (System Automation).

It’s set up by default to send a customer satisfaction survey to your customers 24 hours after their ticket has been solved (not closed). We’ve found that this setup works really well for most companies that have a longer response cycle.

The default conditions for the system customer satisfaction automation:

Customizing when and how the customer satisfaction is requested

But that’s not the end of the story… you can customize the customer satisfaction survey to meet your needs. Customer satisfaction is really nothing but a placeholder that you can use in any notification sent out by a trigger or automation. Yes, Zendesk Support provides you with a system automation specifically for customer satisfaction, but you can modify it, or even remove it altogether and trade it in for a trigger.

As I pointed out earlier, the automation is defaulted to 24 hours. However, you can easily increase or decrease the length of time between when the ticket is solved and when the survey is sent by editing the automation:

If you’re taking advantage of user and organization tagging, you may want to send customer satisfaction to only a subset of your user base. For example, do you want to make sure users tagged with “partner” never get a customer satisfaction survey? Add this condition under “ALL”:

Are you afraid that users are receiving too much email? Consider combining the “solved” email notification with the customer satisfaction survey. To achieve this, simply deactivate the customer satisfaction automation, then go into triggers and edit your “solved” notification trigger. Add the customer satisfaction placeholder {{satisfaction.rating_section}} into your notification. That’s it! Now your “solved” notification will include a customer satisfaction survey:

Customizing the customer satisfaction email

If you want to customize the Satisfaction Survey section of the email notification, you can use system placeholders and HTML to do so. You’ll find the list of available placeholders in the Zendesk Support placeholders reference.

For example, the default {{satisfaction.rating_section}} placeholder will return the following section:

If you use the {{satisfaction.positive_rating_url}} and {{satisfaction.negative_rating_url}} placeholders plus custom HTML, you can transform the satisfaction section to something like this:

Zendesk can’t provide customer support for your custom HTML or CSS. Please post any issues you have in the comments section or try searching for a solution online.

Considerations

When customizing your customer satisfaction process, you’ll want to think about different situations, and what will work best for both you and your customers.

Are you more concerned about customers receiving too many emails? Consider combining customer satisfaction with another email. However, customer satisfaction may not get the attention (or response) when combined with other information.

Also consider the case that a ticket is inadvertently marked as solved, or is solved before the issue is actually resolved for the customer. Sending out the survey in combination could actually result in more negative ratings. Using an automation instead allows a period of time to pass, during which a customer could choose to reopen his or her ticket.

If your response cycles with support are typically shorter (e.g. most tickets take 5 minutes to answer), you may want to actually reduce the amount of time you wait before surveying customers. If your response cycles are measured in hour or days, 24 hours might be adequate. Timing is everything, and a perfectly timed customer satisfaction survey can truly help your response rate.

For more in-depth instructions on configuring Customer Satisfaction, see Using CSAT.

Enabling customer satisfaction ratings

By default, customer satisfaction ratings is disabled. You must be an administrator to enable it.

You can also enable satisfaction reasons, which allow you to add a follow-up question to negative survey responses.

To enable customer satisfaction ratings

1. In Support, Click the Admin icon () in the sidebar, then click Settings > Customers.
2. On the Satisfaction tab of the End-users (customers) page, click Allow customers to rate tickets.

Zendesk Support is now set up to send your end-users the customer satisfaction rating email. Enabling this also creates a new automation called Request customer satisfaction rating (System Automation) and a view called Rated tickets from the last 7 days. Both can be modified as needed to suit your workflow.

For information about using the Explore reports for customer satisfaction, see Viewing your Customer Satisfaction score and ratings.

Using customer satisfaction rating placeholders

Aside from the placeholder mentioned above,{{satisfaction.rating_section}}, the customer satisfaction rating feature adds four other related placeholders. All of these placeholders can be used in various ways and are described in the following table.

Placeholders are best used in triggers and automations. Inserting them into a macro or comment creates a plain text version of the CSAT request, which permits other users to submit a satisfaction score for the requester and requires end-users to click the URL and sign into your Help Center to complete the survey.

Table 1. Customer satisfaction rating placeholders

Reporting on customer satisfaction

You can view CSAT reports on the Satisfaction tab of the Explore Zendesk Support dashboard (see Overview of the Zendesk Support dashboard). If you are using Explore Professional, you can also build your own custom reports based on customer satisfaction data.

If you haven’t enabled Explore, view your score and ratings in the Satisfaction dashboard. For more information, see Viewing your Customer Satisfaction score and ratings.

Applying satisfaction reasons to ticket views

You can create a ticket view to organize tickets by the satisfaction reason given, or to look tickets with a negative response and no satisfaction reason given.

The reasons included in your survey appear as condition elements in the views builder:

For information on building ticket views, see Using views to manage ticket workflow.

Applying satisfaction reasons to business rules

You can create business rules - triggers and automations - based on satisfaction reasons to draw attention to tickets with certain responses.

The reasons included in your survey appear as conditions in the triggers or automations builder:

For more information on triggers and automations, see the following articles:

• Creating and managing triggers
• About automations and how they work

Customer satisfaction rating surveys allow you to measure how happy your customers are with the services you provide. Inevitably, you’re going to receive a less-than-glowing response (rare as it may be). You can learn about the issues behind a bad satisfaction rating by asking any customer who gives a negative survey response to select a reason for their dissatisfaction.

Enabling satisfaction reasons

Satisfaction reasons are managed through the Customers settings.

To enable satisfaction reasons

1. Click the Admin icon () in the sidebar, then select Settings > Customers.
2. On the End-users (customers) settings page, click the Satisfaction tab.

3. In the Configuration Options section, click the checkbox to enable Ask a follow-up question after a bad rating. This opens the satisfaction reasons picklist.

   

4. Click Save Tab to accept the default reasons:

   • The issue took too long to resolve
   • The issue was not resolved
   • The agent’s knowledge is unsatisfactory
   • The agent’s attitude is unsatisfactory

   You can accept these reasons, or create customized reasons. See Customizing satisfaction reasons below for information.

   Once enabled, customers who respond to your survey by selecting “Bad, I’m unsatisfied” see a follow-up question that asks “What is the main reason you are unsatisfied?”, with a drop-down menu to choose their reason:

   

   This follow-up question is optional - customers can skip it by simply ignoring it and clicking Update - and it only appears to customers who select the response “Bad, I’m unsatisfied”.

Customizing and localizing satisfaction reasons

The default reasons address common, service-related issues customers may have, but these may not serve your needs. When you enable satisfaction reasons, you can customize the reasons offered to your customers to better reflect brand and product-specific language, unique customer experiences, and even cultural differences. You can also localize your custom reasons to reach customers in multiple languages.

Customizing the reasons list

There are any number of reasons why you may want to customize the reasons offered to your customers. Maybe you want to clarify whether a customer’s dissatisfaction is with a product rather than the service they received, focus on different aspects of your customer service, or simply change the reasons’ language to match your company’s style.

You can add an additional reason to the default list (up to five reasons are allowed), and remove the default reasons to make room for your custom reasons. However, the default Some other reason cannot be removed from the list.

The order your reasons appear in is randomized for each user, to prevent order bias.

To add a reason to the list

1. Click the Admin icon () in the sidebar, then select Settings > Customers and click the Satisfaction tab.

2. Click the “+” button in the right-hand column and enter text for a new, custom reason.

   

3. Click Enter or click away from the text field to add the new reason to the Reasons not in use column. Reasons in this column do not appear in the customer survey follow-up question.

   

4. Next, move the reason to the Reasons in use column, so it is included as an option in the survey follow-up question.

   

5. Click Save tab. Your new reason is now included as an option in your survey.

While default reasons cannot be deleted, you can move them (as well as any custom reasons) into the Reasons not in use column, to make room for more custom reasons, or just to remove them from the reasons list.

To remove a reason

1. Click and hold the reason in the Reasons in use column you want to remove.
2. Drag the reason into the Reasons not in use column.
3. Click Save tab. The reason is removed from the survey.

To edit a reason

1. Drag the reason you want to edit into the Reasons not in use column.
2. Hover the cursor on the right side of the reason you want to edit. When the cursor symbol changes to a hand, click the reason.
3. Edit the reason text as you need. When you are finished, press enter.
4. Click Save tab.

Localizing custom reasons

You can customize your satisfaction reasons to appear in each of your customer languages, by integrating your reasons with dynamic content (available on Professional and Enterprise plans).

To localize a reason

1. Click the Admin icon () in the sidebar, then select Manage > Dynamic Content.
2. Click add item to add a new dynamic content item.

3. Add a new title for your dynamic content item, select your default language, and enter the translation for this language.

   

4. Click Create to create the new dynamic content item.
5. Click add variant to add a new translation for your dynamic content item.

6. Select a language for your item and enter the new translation.

   

7. Click Create to save the new translation. In this example, the satisfaction reason is localized in English and Spanish and has a new dynamic content placeholder, {{dc.sat_reason_product_issue}}

   

8. Navigate back to Settings > Customers > Satisfaction.
9. Click the “+” button to add a new satisfaction reason.

10. Insert your new dynamic content placeholder into the text field and type “Enter” or click away from the text field. The placeholder gets resolved to the language of the account when saved to make the satisfaction reasons easier to manage.

    

    If available, the translated satisfaction reason will appear in the correct customer language.

    

Using satisfaction reasons in reporting

Customer satisfaction reasons can be used with Zendesk Support’s reporting functionality, on the Satisfaction dashboard, and in Zendesk Insights.

In the Satisfaction dashboard, reasons are included in the Feedback section, as a sortable column, and as filter.

For information on working with the Satisfaction dashboard, see Viewing customer satisfaction score and ratings.

In Insights, users can use satisfaction reasons as metrics to analyze data and build reports.

For information on working with Insights, see Creating reports and dashboards in Insights.

With the Web Widget, you can add customer support features from Zendesk Guide, Support, Talk, and Chat to your website or Help Center, so that your customers can get immediate help from a single interface, in whatever form they like best.

Here are the ways that your customers can get help from the Web Widget:

• Search Help Center articles for immediate self-service.
• Submit a support request using a contact form.
• Request a callback, or view a phone number that they can call instead.
• Start a live chat with an agent.

About the Web Widget

The Web Widget is a separate web application that you embed in a web page that gives customers access your Help Center and the agents in your other Zendesk support channels (Support, Talk, and Chat). It can encourage customers to self-serve, whenever possible, by using Help Center articles. It can also make it easier to get help from an agent by reducing the number of steps required to access a contact form, request a call back, and start a chat.

All of these things can be done from a single interface. The customer doesn’t need to go from your home page to your Help Center, open their email application, or search your website to find a email address to contact you.

You can add the Web Widget to your website or Help Center. It appears in the bottom corner by default.

You must be an administrator to set up and manage the Web Widget.

The first thing you need to do is configure the components you want in the widget (see Configuring the Components in your Web Widget), and then you can add the widget code your website or Help Center (see Adding the Web Widget to your website or Help Center).

For a complete list of documentation about the Web Widget, see Web Widget resources.

Browser requirements for Web Widget

The Web Widget is supported on these browsers.

Understanding the end-user experience

In the Web Widget, you can enable components to combine knowledge base search, live chat, phone calls, and contact forms. The end-user experience depends on what options are enabled and whether agents are online.

When multiple components are enabled in the Web Widget, components are presented to end users in a specific sequence, at different times, rather than all at once.

Components are presented in this order:

1. Self service
2. Live chat
3. Phone calls
4. Contact forms

For more information about how visitors can use these components, keep reading.

Self service

If the Help Center is enabled in the Web Widget, customers are presented with Help Center search first. When the Web Widget opens, it includes both self-service and the contact button.

When you search, up to nine results appear, if matches are found. The customer can click an article in the list and it opens in the Web Widget.

If Contextual Help is enabled in the Web Widget, up to three suggested articles appear below the search box. The suggested articles are determined by the page URL from which the customer accessed the Web Widget, or it is chosen by the administrator using advanced customizations (see About Contextual Help for the Web Widget).

Live chat

This is an overview about how Chat in the Web Widget works from a visitor’s perspective. It’s meant to give administrators and agents a general idea about how it works, but it doesn’t cover all scenarios—the exact appearance and behavior of Chat in the Web Widget depends on how it was configured by the administrator.

Visitors to your website can use Chat functions in the Web Widget from a desktop or mobile browser (see Customizing the Chat widget for mobile devices).

Your visitors can perform these chat-related activities from the Web Widget:

• Starting chats from the Web Widget launcher
• Receive proactive chats
• View conversation history
• Customize the avatar, name, and byline of the chat Concierge section
• Send and receive attachments with chats
• Adjust sound, request transcripts, edit contact details, and end chats
• Translate chats
• End and rate chats
• Popping out the Web Widget during chats

For more information, see Setting up Zendesk Chat in the Web Widget.

Starting chats from the Web Widget launcher

When Chat is enabled in the Web Widget, the appearance of the launcher to end users depends on which other contact options are enabled.

Launcher appearance	Contact options and agent availability
	If Chat is the only contact option enabled in the Web Widget and a Chat agent is online, the launcher includes the Chat icon and says Chat.
	If Chat and the Help Center are enabled, when a chat agent is online, the launcher includes the Chat icon and says Help.
	The chat badge is a special launcher that allows a customer to get support from a chat agent immediately. It’s larger than the default Web Widget launcher button and it doesn’t include other contact options (see Customizing the Chat Badge section). If the chat badge is enabled, chat is the only contact option enabled in the Web Widget, and a Chat agent is online, the chat badge appears on the page instead of the regular Web Widget launcher.
	If Chat is the only contact option enabled and no agents are online, the launcher does not display.

Once the customer opens the Web Widget, they see this:

When the customer clicks Live chat, what they see next depends on whether the pre-chat form is enabled.

If the pre-chat form is enabled, the customer fills in the form, then clicks Start Chat

If the pre-chat form is not enabled, the customer can start the chat right away.

If an agent is available when the customer clicks the launcher, but the then agent signs off before the chat begin, the customer sees a message indicating that the Chat agent is not available.

Receiving proactive chats

Agents can see who is the currently on your site and decide whether to proactively contact a visitor before they request a chat. For example, you might want to reach out to visitors who have items their shopping cart, but are taking too long to complete their purchases.

Viewing conversation history

If visitor authentication is enabled in the Web Widget, authenticated visitors can see their past chats.

Customize the avatar, name, and byline of the chat Concierge section

Before visitors connect with a support agent, they see the avatar, name, and byline of the chat Concierge.

Sending and receiving attachments with chats

Visitors can send and receive attachments. Clicking the attachments icon () opens a standard file selection dialog box, but you can also drag and drop files into the Web Widget too.

Adjusting sound, requesting transcripts, editing contact details, and ending chats

Visitors can use the expandable menu at the bottom () to turn sounds on and off, request a transcript of the chat, edit their contact details, or end the chat.

Translating chats

If Chat detects that the agent and visitor are using different languages, the Show translated link appears in the conversation. Visitors can click this link to translate the agent’s replies into their language. The translation is performed by Google Translate.

Ending and rating chats

When the visitor is ready, they can end the chat by clicking the end chat () icon. They can also end the chat from the expandable menu ().

Visitors can rate a chat as good or bad using the thumbs up () and thumbs down () icons at any time during the chat. After they rate the chat, the Leave a comment button appears, so they can add a comment, if desired.

If the visitor doesn’t rate the chat after a little while, the agent can prompt the visitor to rate the chat by making the Rate this chat button appear.

Popping out the Web Widget during chats

When Chat is enabled in the Web Widget, visitors can click the pop-out icon () to pop-out the Web Widget to it’s own browser window.

The Web Widget becomes separate from the website and receives a unique URL. It can be moved around and is no longer anchored to the website.

You can share the URL to the Web Widget popout in a range of marketing communications, inviting the user to engage directly with you without having to be on your website.

Phone calls

When Talk is enabled in the Web Widget, the appearance of the launcher to end users depends on which other contact options are enabled.

Launcher appearance	Contact options and agent availability
	If Talk is the only contact option enabled in the Web Widget and an agent is online, the launcher includes the Talk icon and says either Request a callback or Call us, depending on your configuration.
	If Talk and the Help Center are enabled in the Web Widget, and an agent is online, the button says Help.
	If Talk, the Help Center, and Chat, or contact forms are enabled in the Web Widget, and agents are online, the launcher includes a question icon and says Help.

When the Web Widget opens, the exact appearance of Talk in the Web Widget depends on the how it’s configured by the administrator and the status of agents (see Configuring Zendesk Talk settings for the Web Widget). Depending on your configuration, customers can:

• View a phone number that they can call
• Request a callback
• View the average wait time for a callback

The following examples show how Talk in the Web Widget might appear, depending on your configuration.

If Talk is the only option enabled in the Web Widget and it is configured to allow callback requests, and then you click the launcher, the callback form displays.	If Talk is the only contact option enabled and Talk is configured for Call Us only, your phone number displays.

If Talk and the Help Center are enabled, and other contact options are enabled (for example, Chat or contact form), after a Help Center search the customer can access Talk from the Contact us button.	If Talk and the Help Center are enabled, and Chat and contact form are disabled, after a Help Center search the Contact us button says Request a callback (or Call us) instead.

Contact forms

Your customers can submit a ticket from the Web Widget to receive an email reply to their inquiry. The contact form is enabled in the Web Widget by default.

By default, the contact form includes fields for the customer’s name, email address, and a description of the problem. If the administrator enabled multiple ticket forms in the Web Widget (see Configuring the components in your Web Widget), then the customer can choose from multiple ticket forms. If not, then only the default contact form appears.

Tickets submitted through the Web Widget contain the tag web_widget.

Before you add the Web Widget to your website or Help Center, you need to decide which components you want to include in the Web Widget and then turn them on. For some components, you might need to go a step further and configure additional settings. You must be an administrator to configure components in Web Widget.

You can configure the Web Widget to include any combination of these components:

• Help Center search and suggested articles
• Zendesk Chat for live chat with an agent
• Zendesk Talk for requesting a callback from an agent or viewing a phone number to call
• Contact forms for filing a ticket

Configuring the Web Widget

The Web Widget includes multiple components that you can turn on or off, or customize. For example, you can add help, talk, and chat features, and contact forms. You can configure security settings, change the color of buttons and text, edit user interface text, and reposition Web Widget. If you have an Enterprise account, you can remove the Zendesk logo.

For detailed information about the components you can configure, see Configurable Web Widget components (below).

To configure the Web Widget

1. Click the Admin icon () in the sidebar and then navigate to Channels > Widget.

   If you are setting up the Web Widget for the first time, a wizard guides you through the process. Follow the on-screen prompts. After you complete the wizard, you can view and change your options, if you want, by proceeding to the next step.

   If this isn’t your first time setting up the Web Widget, skip this step. The wizard doesn’t appear for you.

2. From the Customization tab, configure your Web Widget components (see Configurable Web Widget components below).

3. When you’re done configuring components, click Save.

   Allow 10 minutes for changes to the Web Widget to propagate and appear in the Web Widget.

   Once you’re done with this procedure, you’re ready to complete the steps described in Adding the Web Widget to your website or Help Center, if you haven’t already.

Configurable Web Widget components

This table lists the Web Widget components that you can configure from Support.

If you want to customize the Web Widget further, it’s possible to do that using the Web Widget API, but you might need the help of a website developer. For more information, see Advanced customization of the Web Widget.

The Web Widget can be added to any page of your website or to your Help Center.

The Web Widget is fully optimized for the mobile experience and does not affect page load times. The widget is presented in the end user’s language, according to the language setting for end user’s web browser. You can force the widget to always appear in a specific language (see Displaying your widget in a different language).

You cannot use SSO authentication in the Web Widget itself. However, you can restrict access by setting up SSO on your Help Center, or on the website hosting the widget. See Single sign-on options in Zendesk and Using restricted Help Center content with the Web Widget.

Adding the widget to your website

You can add the Web Widget to any page of your website. After you add the code, you manage changes in Zendesk Support and with the Advanced Customization JavaScript APIs, and updates are reflected in the widget wherever it appears.

To add the Web Widget to your website

1. Click the Admin icon () in the sidebar, then select Channels > Widget.
2. Click the Setup tab, if it is not already selected.
3. Under the code box, click Copy to clipboard.
4. If you want to add the widget to your website, go to the web page where you want to add the widget, then paste the code before the closing HTML </body> tag. Add the code to every web page where you want the widget to appear.

If you haven’t already, make sure you configure the components in your widget. For information about configuring the Web Widget using JavaScript APIs, see the developer docs.

If the Web Widget does not appear on pages outside your Help Center, you most likely have the Require sign in option enabled in your Guide security settings (see Restricting Help Center access to signed-in end-users).

The Web Widget displays Help Center content that the user is allowed to see. When Require sign in is enabled, and only the Help Center and Contextual Help toggles are on in your Web Widget admin settings, the Web Widget will not load for non-authenticated users. If you enabled other options in your Web Widget admin settings, such as Contact form, the Web Widget does appear.

Adding the widget to your Help Center

You can add the Web Widget to your Help Center, so that it appears on every page of your Help Center. If you’re on the Team, Professional, or Enterprise Support plan, you can restrict the pages where the Web Widget appears in your Help Center by using the Web Widget API.

To add the Web Widget to your Help Center

1. Click the Admin icon () in the sidebar, then select Channels > Widget.
2. Click the Setup tab, if it is not already selected.

3. Click the Add to Help Center toggle.

   

   This adds the Web Widget to the Help Center header document_head.hbs, and displays the widget on every page of your Help Center. For more information, see Customizing your Help Center theme (Guide Professional and Enterprise).

If you’re on the Team, Professional, or Enterprise Support plan, you can restrict the pages where the Web Widget appears in your Help Center by using the zE.hide() method of the Web Widget API. See Advanced Customization of your Web Widget and the Web Widget API documentation for more information.

You can modify the appearance of some or all of the following widget elements to match the look and feel of your company’s website.

If you’re using a Legacy Chat version, see (Legacy Chat) Customizing the appearance of your widget.

The following elements can be modified via the Chat dashboard, under the Appearance tab:

• Chat Window, which includes the title bar text or mobile widget configurations, depending on your version of Chat.
• Concierge, what Chat visitors see before connected to an agent.
• Message Style (Team, Professional, and Enterprise plans only), display options for outgoing Chat messages.
• Chat Badge (Chat Standalone only), how the widget looks before a chat is started.

To customize the widget’s appearance

1. From the Chat dashboard, go to Settings > Widget and click the Appearance tab.
2. Customize the options as described in the sections below.
3. Preview your changes in the Preview pane on the right. The changes displayed in the Preview pane depends on which version of Chat you are using. Expected Preview pane behavior for each section in the Appearance tab is described in the sections below.
4. Click Save Changes.

Customizing the Chat Window section

The Chat Window section is where you configure elements related to the frame around a chat between an agent and a customer. The options you see here depend on which version of Chat you’re using.

Chat + Support in the Web Widget users

Here, you can customize the Top Title Chat Window element. This text appears on the top of your chat window. The following example shows the top title with the text “Chat with us”:

Standalone Chat in the Web Widget users

Here, you can customize the following Chat Window elements:

• Top Title: This text appears on the top of your chat window. The following example shows the top title with the text “Chat with us”:

  

• Theme Color: This is the color your widget is outlined in. Enter a hex code or click the swatch to manually select a color.
• Widget Position: Select whether the widget should appear on the bottom right or bottom left of pages you add it to.

Chat widget users

Here, you can customize the mobile widget:

• Overlay window: The chat window opens on top of your mobile site in the same tab (recommended).

• Chat Popout: The chat window opens in a new tab.

Customizing the Concierge section

Before visitors connect with a support agent, they see the avatar, name, and byline of the chat Concierge.

• Display Title and Byline: This text appears at the top of the chat window. The following example shows the Display Title “Live Support” and the byline “Ask us anything”.

  

• Avatar (Team, Professional, and Enterprise plans only): Upload a custom image of the avatar you want to appear for your chat Concierge.

Customizing the Message Style section

These options are available only on Team, Professional, and Enterprise plans.

• Message Style: With the Speech Bubbles option, bubbles appear around each chat sent. Simple Lines just shows the text.

• Show Avatars: Check this box to show agents’ and visitors’ avatars next to each chat they send.

Customizing the Chat Badge section (Chat standalone users)

The chat badge is how the widget looks before a chat is started.

• On or Off: Enable or disable the chat badge.

• Image Right, Image Left, or Text Only: These options determine how the layout of the chat badge looks. Image Right and Image Left use the default chat bubble image, which you can see in the Preview pane.

• Custom Image: To use your own image, select Custom Image and upload an image in the Image field below.

• Background Color: Enter a hex code or click the swatch to manually select a color for the chat badge background. To use the same color as the Theme Color from the Chat Window section, check the Same as Theme Color box.

• Message: This text appears inside the chat badge before your visitors click on it. The following example shows the badge with the text “Chat with us”:

  

• Image: If you selected Custom Image above, upload an image for your chat badge here.

You can remove individual instances of your widget by deleting the code from the web page or Help Center. You can turn off all instances of the widget by disabling it in Zendesk Support.

To remove the widget from a web page

• Delete the code from the web page.

To remove the widget from your Help Center

1. Click the Admin icon () in the sidebar, then select Channels > Widget.
2. Click the Setup tab.
3. Click the Add to Help Center toggle to remove the widget.

To disable the widget and prevent it from appearing on your website and Help Center

1. Click the Admin icon () in the sidebar, then select Channels > Widget.

2. Click the Customization tab.

3. Beside Contact form, Chat, and Help Center, click each toggle to Off.

   

   All three widget components must be turned off.

4. Click Save. The widget will not appear on your website or Help Center.

You can organize your knowledge base content into categories and sections and manage the order of those categories and sections.

You must be a Guide Manager to add and edit sections and categories.

Adding a category to your knowledge base

Categories are the top-level organizing containers of the Help Center and at least one must exist. Categories contain sections. If you have only one category in your Help Center, then the category itself is hidden to end-users, and they see only the sections in your Help Center.

For more information, see About the Help Center knowledge base structure.

To add a category

1. In Help Center or Guide Admin, click Add in the top menu bar, then select Category.

   

2. Enter a Name and optional Description for your category.

3. (Guide Enterprise) In the sidebar, if you have multiple category templates in your live theme, click the Template menu, then select a template.

   If you do not select an alternate template, the default category template will be applied.

   

4. In the sidebar, ensure the correct Source language is selected.
5. Click Add.

The category is created. Remember, if you have only one category, then the category itself is hidden to end-users, and they see only the sections that are in your Help Center.

For information about how you can display a section in multiple categories, see Displaying an article or section in multiple sections or categories in our Support tech notes.

Adding a section to your knowledge base

Sections are collections of related articles. To add a section, you must have at least one category to act as its parent container.

• On Guide Lite and Professional, each section must be child of a category.
• On Guide Enterprise, a section can be a child of a category or a section.

Permissions for viewing and managing articles in a section are set at the article level, not the section level.

If visibility for all the articles in a section is internal (Professional and Enterprise only), then the section will not be visible to end-users, but if one article in an internal section is visible to any end-users, then the section will become visible as well.

To add a section

1. In Help Center or Guide Admin, click Add in the top menu bar, then select Section.

   

2. Enter a Name and optional Description for your section.
3. (Guide Professional and Enterprise) Ensure the correct Source language is selected if you support multiple languages.

4. Under Order articles by, select an option for how you’d like articles to appear in this section.

   If you select to manually order of articles, see Manually changing the order of articles to change the order of your articles.

5. Under Hierarchy, click in the field, then select where you’d like this section to appear in your Help Center.

   On Guide Lite and Professional, you must select a category as the parent for this section. Sections cannot contain sections.

   On Guide Enterprise, you can select a category or a section as the parent for this section. You can nest sections in sections for a maximum of five section levels, with up to 20 sections in a section.

6. (Guide Enterprise) If you have multiple section templates in your live theme, click the Template menu, then select a template.

   If you do not select an alternate template, the default section template will be applied.

7. Click Add.

   The section is created. Remember, if you have only one category, then the category itself is hidden to end-users, and users see only the sections that are in your Help Center.

Deleting categories and sections

When you delete a category, all the sections contained in the category are also deleted, and all the articles contained the sections are archived.

When you delete a section, all the articles contained in the section are archived.

To delete a category or section

1. Do one of the following to edit the category or section you want to delete:

   • In Help Center, navigate to the category or section you want to delete, then click Edit section in the top menu bar.

     

   • In Guide Admin, click the Arrange content () icon in the sidebar and drill down to the category or section you want to delete. Click the options menu at the end of the section title, then select Edit category or Edit section.

     

2. Click Delete in the bottom of the sidebar.

3. Confirm that you want to delete the category or section.

   Alternatively, to delete a category or section, you can click Articles > Arrange articles, then click the name of the category or section you want to delete (you’ll have to expand a category to see its sections).

   In the edit page, click Delete in the bottom of the sidebar.

   You cannot recover deleted categories or sections. Any articles contained in a deleted section are archived and you can restore archived articles to another section if you need to.

Working with category and section drafts

If you create a category or section that is a work in progress, and want to restrict who can access it, you can mark it as a draft. Marking a category or section as a draft applies the draft status to any elements within it.

The steps for marking a newly-created category or section as a draft are slightly different than those for marking an existing category as a draft.

To mark a newly-created category or section as a draft

1. Create and save a new section or category, as described in Adding a category to your knowledge base or Adding a section to your knowledge base.

   The section or category is created and remains open for editing.

2. Click the Mark as draft option in the sidebar.

   

3. Click Update at the top of the page.

To mark an existing category or section as a draft

1. Open the category or section in edit mode, as described in Editing categories and sections.
2. Click the Mark as draft option in the sidebar.
3. Click Update at the top of the page.

Categories and sections marked as drafts are not viewable by end-users, and can only be accessed by Guide Managers.

To determine whether a category or section is marked as a draft

• Open the category or section in edit mode, as described in Editing categories and sections.
• An existing category or section in draft mode section in draft mode is indicated by the Draft label at the top of the edit page:

• A new section added to a category in draft mode displays a banner at the top of the page:

When the category is published, the section is no longer in draft mode, and the banner is removed. However, if the section is manually marked as draft, it will remain in draft mode until the marker is removed.

As your Help Center grows, you may find that you need to move existing sections from one category to another, or move articles from one section to another.

Moving a section to a different category

You can to move an existing section from one category to another.

There are two ways to do this. You can either navigate to the section in Help Center and edit it or you can navigate to the section in Guide Admin and move it.

To move a section to a different category in Help Center

1. In Help Center, navigate to the section you want to move, then click Edit section in the top menu bar.

   

2. Under Hierarchy in the sidebar, click the name of the current category.

3. Select a new category for the section, then click Select.

   You can search for or navigate to the category. All of your categories might not appear in the window.

4. In Edit section, click Update.

To move a section to a different category in Guide Admin

1. In Guide Admin, click the Arrange content () icon in the sidebar.
2. In Arrange articles, drill down to the section you want to move.

3. Click the options menu at the end of the section title, then select Move to.

   

4. Select a new category for the section.

   You can search for or navigate to the category. All of your categories might not appear in the window.

5. Click Move.

Moving an article to a different section

You can move an existing article from one section to another.

There are two ways to do this. You can either navigate to the article in Help Center and edit it or you can navigate to the article in Guide Admin and move it.

To move an article to a different section in Help Center

1. In Help Center, navigate to the articles you want to move, then click Edit article in the top menu bar.

   

2. (Guide Enterprise only) Click Article settings.
3. Under Publish in section, click the name of the current section.

4. Select a new section for the article, then click Ok.

   You can search for or navigate to the section. All of your categories might not appear in the window.

5. In Edit article, click Update.

To move an article to a different section in Guide Admin

1. In Guide Admin, click the Arrange content ) icon in the sidebar.
2. In Arrange articles, drill down to the article you want to move.

3. Click the options menu at the end of the article title, then select Move to.

   

4. Select a new section for the article.

   You can search for or navigate to the section. All of your categories might not appear in the window.

5. Click Move

The article is moved to the new section.

You can access a complete list of your archived articles. You can restore an article from your archived list if you want to make it available again in your knowledge base.

You must be a Guide Manager to view and restore archived articles. For information about archiving an article, see Archiving an article to remove it from your knowledge base.

Viewing the archived articles list

You can access a complete list of your archived articles. An archived article remains in your list unless you delete it.

You must be a Guide Manager to view archived articles.

To view a list of archived articles

1. In Guide, click the Manage articles () icon in the sidebar.

   The Lists tab opens by default.

2. Click Archived articles.

   

   A list of your archived articles appears. You can add filters to view a subset of all your archived articles.

Restoring an archived article

You can restore an archived article if you want to make it available again in your knowledge base. You cannot disable the ability to restore articles. If you need to restore multiple articles at once, see Updating knowledge base articles in bulk.

You must be a Guide Manager to restore archived articles.

To restore an archived article

1. In Guide, click the Manage articles () icon in the sidebar.

   The Lists tab opens by default.

2. Click Archived articles.

   A list of your archived articles appears.

3. Find and select an archived article from your list.

   You can browse, search, or add a filter to find a specific article.

4. In the archived article, click Restore.

   The article is restored as a draft or work in progress, depending on your plan type, in the section where it was previously published. If the section no longer exists, you are prompted to select a new section.

5. When you are ready to publish the article, click the drop-down arrow on the Save button, then select Publish now.

From an articles list, you can update one or more articles at once using the bulk actions options. For example, you can publish a batch of articles at once or add a labels to several articles.

You can make the following updates using bulk actions:

• Archive or restore articles
• Delete articles
• Change author
• Open or close for comments
• (Guide Professional and Enterprise) Change labels on articles
• (Guide Professional and Enterprise) Change user permissions
• (Guide Enterprise only) Assign or unassign articles
• (Guide Enterprise only) Submit articles for review
• (Guide Enterprise only) Submit articles for approval
• (Guide Enterprise only) Schedule articles for publishing
• (Guide Enterprise only) Schedule articles for unpublishing
• (Guide Enterprise only) Verify or unverify articles
• (Guide Enterprise only) Change article owner
• (Guide Enterprise only) Publish or unpublish articles

To update articles in bulk

1. In Guide, click the Manage articles () icon in the sidebar.
2. Find the articles you want to update by browsing, searching, or using a new or existing articles list.

3. Select one or more articles to update.

   You can select a maximum of 30 articles at a time. To select 30 items at once, click the check box beside the number of results at the top.

   

4. Click one of the bulk actions menus at the bottom, then select an option.

   The bulk actions that are available depend on your plan.

   

5. Click to confirm that you’d like to perform the action, or enter your update, if necessary.

   Some actions require an additional step:

   • For assign, select a team member and enter a note, then click Assign.
   • For change labels, select or deselect labels to add or remove them or enter a new label, then click Change.

   For more information, see Updating article labels in bulk.

   • For restore, select a section for the article, then click Restore.
   • For scheduled publishing and unpublishing, click to create a schedule to publish or unpublish an article. Select a date, time, and time zone, then click Schedule.

   You can select both check boxes to create a publish schedule and unpublish schedule in one action.

   The action is applied to all the selected articles.

Labels are a single word or a multiple word phrase you can add to the default language version of a specific article in Help Center. You can use labels to influence article search relevance, to influence Answer Bot results (if you are using Answer Bot), or to create a list of related articles based on labels.

You can add and remove labels on individual articles or you can change labels on multiple articles at once. You must have Guide Professional or Enterprise to use article labels.

Adding and removing labels on individual articles

Labels are a single word or a multiple word phrase you can add to the default language version of an article in Help Center. You can add articles labels for multiple purposes, including to influence search and Answer Bot results or to create article lists (see Understanding why to use labels).

You can add and remove labels on individual articles or you can change labels in bulk for multiple articles at once.

To add or remove labels to an article

1. In Help Center or Guide, navigate to the article where you want to change labels, then click Edit article in the top menu bar.

2. (Guide Enterprise only) If you are on Guide Enterprise, click Article settings. This step is not necessary on Guide Professional.

3. In Labels in the right sidebar, start typing the label you want to add, then select Add as new label or select the matching label, if it exists.

   You might have to scroll down to see labels. See Best practices for adding labels below.

   

   Labels live on the default language article and not on translations of the article. If you have translations, you can add labels in multiple languages to the default article.

4. Add multiple labels as needed.

5. If you need to remove a label, click the x beside the label name.

6. Click Save.

You must manage labels on each individual article or using the API. There is no global management for article labels.

Changing article labels in bulk on multiple articles

You can add or remove labels to on multiple articles at once.

1. In Guide, click the Manage articles () icon in the sidebar.

2. Find the articles you want to update by browsing, searching, or using a new or existing articles list.

3. Select one or more articles to change labels.

   You can select a maximum of 30 articles at a time.

   

4. Click the Article settings menu at the bottom, then select Change labels.

5. Do any of the following:

   • Add a new label: Enter the label, then click Add as a new label.

   

   • Add an existing label: Search or browse to find the labels you want to add, then select any empty checkbox or any checkbox with a minus.

   The minus sign () indicates that the label appears on some but not all of the selected articles. When you select it, it changes to a checkmark (), indicating that it will be added to any selected article that doesn’t already have that label.

   You can select multiple labels to add to the selected articles.

   

   • Remove an existing label: Search or browse to find the labels you want to remove, then deselect one or more labels.

   The checkmark () indicates that the label appears on all of the selected articles. The minus sign () indicates that the label appears on some but not all of the selected articles. When you select a checkbox with a minus sign, it changes to a checkmark.; click it again to deselect the checkbox.

   You can select multiple labels to add to the selected articles.

   

6. Click Change.

   The label changes are applied to the selected articles.

Understanding why to use labels

Labels have the following uses and impacts:

• Influence article search relevance

  Adding labels can make your articles more search friendly. They are not designed to be used for fine-grained control of ranking. For example, if I have two articles about making waffles, one with the word “temperature” in the body of the article, one with the label “temperature”, the labeled article will be ranked higher if a user searches for the word “temperature”.

  Labels are indexed for search with a bit less weight than the article title, but multiple labels with similar words can outweigh the title and body of the article. Use labels carefully as you can significantly impact the relevance of your search results and usefulness. If you are considering using labels to impact search relevance, consider that efforts to do so could end up with inferior ranking performance for your users. The best way to have your article perform well in search is to create a short and focused article, where the title and body include keywords and clearly connect to each other.

  To learn more about search, see How end-user search works in Help Center.

• Influence Answer Bot results

  Answer Bot uses labels to influence the results it shows. It allows you to define a whitelist of articles that are allowed to be used when looking for relevant matching results. You are able to add up to ten labels that serve as an OR filter, allowing you to expand the whitelist to any articles containing any of the defined labels.

  To learn more about Answer Bot, see About Answer Bot.

• Create article lists

  Article lists enable you to get an overview of all your published and unpublished knowledge base content, and then refine that view by using search and applying filters to build article lists. For example, you can find articles that have a specific article label, such as out-of-date.

  To learn more about article lists, see Creating article lists to different views of your knowledge base content.

Best practices for adding labels

Labels can help boost the search relevance of an article. However, you should use labels carefully and sparingly. It’s more important to make sure the article title and body contain the relevant keywords.

• Use single word labels where possible, instead of multi-word phrases

  It is possible to add labels as single words or as multiple words or phrases. In general, it’s more efficient to use single word labels. If you add a multi-word label, the search engine breaks it into individual words to perform the search. For example, if you have a label of “late delivery,” it gets broken down into “late” and “delivery” for search.

  Avoid using long phrases as labels to boost an article’s ranking with respect to a query. For example, “Can I return something I ordered online to my local store.” Instead, you should modify the article’s title or content to make it literally relevant to the query.

• Do not include variations of the same word, including different tenses or plural forms

  You do not need to include multiple labels for variations of a word. For example you do not need a label for “return” and “returns” or “update” and “updated.” Search stemming allows different forms of the same word to match. In particular, the singular and plural forms of a word will generally match.

• Use a limited number of labels, instead of overloading an article with labels

  Use labels sparingly. Adding lots of labels might actually diminish any matches on labels. This is because it is assumed that matches with a fewer number of labels beats matches with more labels. And too many labels might outweigh the relevance of the title and body.

  For example, if article 1 has the labels “car,” “automobile,” and “transport” and article 2 has only the label “car,” all other things equal, if the end-user searches for “car,” the article that has only the label “car” will rank higher. That is because, as a general principle, an article that is about one specific thing is more relevant than an article about many things, when a user is looking for that one specific thing.

  The number of labels for search is limited to 200. The search engine will use the first 200 labels and ignore any additional labels.

  Your best bet is to look at the top ranked search queries and make sure that they exist in either (but not both) the title or the labels. You don’t give content an extra boost if you match a term across the title, body, labels, and comments.

Using the Help Center API to filter articles by labels

There are two ways you can filter articles by labels using the Help Center API:

• Article: /api/v2/help_center/en-us/articles.json?label_names=foo​
• Search: /api/v2/help_center/en-us/articles/search.json?label_names=foo

These two endpoints behave differently and will return different article results. They are programmatically different and query different data sources for their results.

You can import Google Docs into your Guide knowledge base. You can import up to 100 docs at a time. This is a great way to add new content or migrate existing content to your knowledge base.

When you import a Google doc, there is no connection between the new article and the original Google Doc; the article is not synced with the Google Doc. You cannot export articles from your knowledge base to Google Docs.

You must be a Guide Manager to connect to a Google Drive and import Google Docs.

To import a Google Doc

1. In Guide, click the Arrange content () icon in the sidebar, then click Import articles.

2. Click Connect to sign in to your Google account, if you are not already signed in.

   If you have not yet connected Guide to your Google Drive account, clicking Connect takes you through the process of signing in to your account and granting Zendesk Guide.

   

3. Click Next.

4. In Select documents, click Open file picker.

   You will see all the folders and files that you have access to.

   

   Use the options in the upper-right to toggle between grid and list view or to sort your files.

5. Search or navigate to the file(s) you want to import, then click Select.

   You can select up to 100 files to import at a time.

   The file appears in the Import Articles admin page. You can click Redo document selection if you need to choose a different file.

6. Click Next.

7. In Place documents, click Select section to choose a section in your Help Center for this article.

   The articles will not be published when they are imported. Docs are imported as draft articles (Lite and Professional) or work in progress articles (Enterprise).

8. Click Next.

9. In Start import, click Start import.

   Don’t close the window while the importer runs. The time it takes depends on how many docs you are importing.

   Your docs will be imported as draft articles (Lite and Professional) or work in progress articles (Enterprise).

10. When the import finishes, click Have a look to go to Arrange articles and find your articles or click Start a new import to import more Google docs.

    There is no connection between the resulting new articles and the original Google Docs; the articles are not synced with the Google Docs.

    To access your articles later, you can find them in your list of drafts or your list of work in progress (Enterprise).

Guide managers can create new articles and edit all existing articles in the knowledge base. Agents who are not Guide managers can create and edit articles if they have management permissions. End-users can’t contribute articles to the knowledge base.

Light agents on Guide Lite and Professional cannot create or edit articles. Light agents on Guide Enterprise and Legacy can create and edit articles where they have permission.

You must have at least one section in the knowledge base before you can start adding articles. When you create an article, you must assign it to a section. For more information, see Anatomy of the Help Center.

Adding articles to the knowledge base

Guide managers can create new articles. Agents can create new articles if they have management permissions. Agent privileges for new articles vary depending on their management permissions. See the complete list of agent privileges for existing, published articles.

You can create a maximum of 40,000 total articles, including translations. This limit includes articles in all states, except archived.

To add an article to the knowledge base

1. In Help Center or Guide, click Add in the top menu bar, then select Article.

   

2. Enter your content.

   • Use the article editor’s toolbar for formatting options or to add links, images, or tables. This toolbar is not the same as the toolbar in community posts.

     

     For information, see the Help Center article editor toolbar reference. See also Inserting links, Inserting images, and Inserting videos. For tables, check out this formatting tip.

   • Edit the HTML source by clicking the Source Code button at the end of the editor’s toolbar.

     Help Center quarantines unsafe HTML tags and attributes to reduce the risk of malicious code. For information, see Allowing unsafe HTML in pages.

3. Under Managed By, click the drop-down arrow, then select management permissions to determine which agents have editing and publishing rights for this article.

   • Managers enables only Guide Managers to edit and publish the article. This option is selected by default on new articles.
   • Editors and publishers (Enterprise only) enables all agents and managers to edit this article but only managers can publish the article. This option appears only if it’s been activated.
   • Custom management permission (Professional and Enterprise) enables specific user segments to edit and publish the article.

   Depending on your account, you might also see an agents and managers option.

   Guide Managers can apply any management permissions. Agents with management permissions can apply only the management permissions they belong to. Agents who do not have management permissions on any article will not see this option, and the management permissions will default to managers.

4. Under Visible to, select one of the view permissions options to determine which users can view this article.

   • Visible to everyone includes anyone who visits Help Center and does not require sign in.
   • Signed-in users includes internal and external users who create an account and sign in to your Help Center.
   • Agents and managers (Professional and Enterprise) includes staff members only, so that you can create content that is internal-only.
   • Custom user segment (Professional and Enterprise) enables you to restrict viewing access to specific users based on tags, organizations, or groups by applying custom user segments (see Creating user segments to restrict access).

   Guide managers and agents with publishing permissions can set view permissions for articles. Agents who do not have publish permissions on any article will not see this option, and the view permissions will default to agents and managers.

5. Under Publish in section, click Select a section, then select a new section and click Ok.

   You can search for or navigate to the section. All of your categories might not appear in the window. To navigate, click the expander arrows to drill down to the section you want.

   

6. Chose any of the following options:

   • To close the article for comments, deselect Open for comments.
   • To promote the article in its section, select Promote article.
   • To add an attachment, click Upload attachment on the lower side of the editor.

   The file size limit is 20 MB. You can remove an attachment by clicking the x next to it.

7. (Guide Professional and Enterprise) Under Labels, add any labels you want.

   As you start typing, a list of existing labels appears for you to chose from, or you can add a new keyword by selecting Add as a new label or by typing a word and pressing Enter.

   

   For more information about using labels and best practices, see Using labels on Help Center articles.

   You can add labels to the default language article only and not to translations of the article. You can add labels in multiple languages to the default article.

8. (Guide Enterprise) Under Template, if you have multiple article templates in your live theme, click the drop-down, then select a template.

   You might have to scroll down to see this option. If you do not select an alternate template, the default article template will be applied.

   

9. When you are finished working on your article, do one of the following:

   • To save your new article as a draft or work in progress to publish later, click Save.

     

     Clicking Save creates the article as a draft (Guide Lite and Professional) or a work in progress (Guide Enterprise).

     Click the Preview in Help Center link (Guide Lite and Professional) or the Preview link (Guide Enterprise) to view the article in your Help Center. The preview link expires after one hour.

   • To publish your new article, click the drop-down arrow on the Save button, then select Publish now.

     Clicking Publish now creates the article and publishes it in your Help Center.

     Click the Show in Help Center link (Guide Lite and Professional) or the Published link (Guide Enterprise) to view the article in your Help Center.

For information about how you can display an article in multiple sections, see Displaying an article or section in multiple sections or categories in our Support tech notes.

Editing articles in the knowledge base

Guide managers can edit any articles. Agents can edit existing articles where they have management permissions. Agent privileges for existing articles vary depending on their management permissions. See the complete list of agent privileges for existing, published articles.

On Guide Lite and Professional, you cannot save edits for an existing published article. On Guide Enterprise, you can save edits for an existing published article as a work in progress.

There are some article updates that you can make on multiple articles in bulk. For more information, see Updating knowledge base articles in bulk.

To open an article in edit mode

• In Help Center, navigate to the article you want to edit, then click Edit article in the top menu bar.

  

• In Guide Admin, click the Manage articles () icon in the sidebar, search for the article, then click the title to open it.

• In Guide Admin, click the Arrange content () icon in the sidebar, navigate to the article, then click the options menu at the end of the title and select Edit article.

The Help Center article editor contains a toolbar you can use to format your knowledge base articles. The article toolbar is not the same as the toolbar that appears in community posts.

The following table describes the formatting options that are available.

Toolbar button	Name	Action
	Paragraph	Insert HTML headings
	Size	Increase or decrase font size
	Bold	Bold or unbold text
	Underline	Underline or remove underline from text
	Text color	Change text color using the color selector
	Italic	Italicize or remove italics
	Numbered list	Create or remove a numbered list
	Bulleted list	Create or remove a bulleted list
	Align/indent	Align text left, center, or right; indent or outdent text
	Insert/edit link	Create or edit a link and link text. You can link to a URL, heading in the article, or another article. See Inserting links.
	Insert image	Insert an image using the file browser. The image file size limit is 20 MB. See Inserting images.
	Add video	Insert a video that is hosted on a supported service. See Inserting videos.
	Table	Create or modify tables using the menu options
	Source code	View or edit the HTML source code

You can insert videos in the body of your Help Center knowledge base articles, either through the article editor toolbar, or by embedding code in your article.

Inserting videos from the article editor toolbar

Guide supports a number of third-party video hosting services as standard. If your video is hosted on one of the following supported video hosting services, you can insert directly from the article editor toolbar:

• Vimeo
• YouTube
• Wistia
• JWPlayer
• Brightcove
• Vidyard
• Loom

If you are using Web Widget on your website or Help Center, your end-users can stream videos in Help Center articles directly in the Web Widget. To display correctly in the Web Widget, videos must be publicly available, and hosted on one of the supported third-party services.

To insert a video in an article using the article editor toolbar

1. Copy the URL for your video.

   Your video must be hosted on Vimeo, YouTube, Wistia, JWPlayer, Brightcove, Vidyard, or Loom. If your video is on one of the supported services, you can use this procedure to insert your video. You do not need to enable the option to allow unsafe content in your Help Center to do so.

   If your video is not hosted on a supported provider, you’ll need to insert the video by embedding code).

2. In Help Center or Guide Admin, edit an existing article or create a new article.

3. Place your cursor where you want the video to appear, then click Add video on the editor’s toolbar.

   

4. Paste the video’s URL in the dialog box.

   A preview of the video appears.

   

5. Click Insert.
6. When you are ready, click Save.

Inserting videos by embedding code

If your video is hosted on a non-supported service, use the article source code editor to add the video’s embed code to insert the video. Be aware that this means you must allow unsafe HTML (see Allowing unsafe HTML in pages).

Some third-party video hosting services do not count video views unless you have manually embedded the code to insert the video. Use the embed method if you need to track video views as part of your analytics.

You can insert images in the body of your Help Center knowledge base articles. When you insert images, they are added as attachments to the article. Large images are automatically resized to fit the width of the article.

Be sure to insert the image, as opposed to copying and pasting the image from another source, to avoid image issues. As an alternative to inserting images directly in your articles, you can host your images on a public file server and link to them.

To insert an image in an article

1. In Help Center, create a new article or edit an existing article.
2. Place the cursor where you want the image to appear.

3. Do one of the following:

   • Drag and drop the image into the body of the article.
   • Click the Insert image button on the toolbar, then click Upload images and select your image.

   

   The image file size limit is 20 MB.

   Images are automatically adjusted to fit the width of the article, using a compression feature within CSS. It’s a good idea to manually resize images that are more than 1600px wide, as the compression might cause the image to appear distorted in the published article. You also might want to manually resize images if you are using Web Widget (see Optimizing images for Web Widget below).

4. Click Insert in the dialog that appears.

   The image appears in your article.

5. Click Save.

If you have a closed Help Center that requires all users to sign-in, article images will appear broken in email notifications sent to users who are following your Help Center. This is a known issue.

Optimizing images for the Web Widget

To make sure the images in your Help Center articles display correctly in the Web Widget, it’s important that the images are added to the article at the desired size.

When Help Center articles are converted for viewing in the Web Widget, the article’s images are stripped of their attributes in the HTML tags (except for the src and alt attributes), and custom CSS rules are ignored. For most images this isn’t a problem, however if the original images are very big they can appear awkwardly large.

Resizing the original image to the size you want, rather than manipulating the size using CSS or width and height attributes, ensures that images will be displayed properly.

Guide managers can create, edit, and remove links in any new or existing article in the knowledge base. Agents who are not Guide managers can create, edit, and remove links in articles where they have management permissions.

Inserting links in articles

You can insert a link in an article for existing text or at the point where your cursor appears.

To insert a link in an article

1. In Help Center or Guide Admin, create a new article or edit an existing article.

2. Highlight text or place the cursor where you want the link to appear, then click Insert/edit link on the editor’s toolbar.

   

3. In the dialog box, do one of the following:

   • To link to a URL, in the URL tab, paste in the link URL. For example, https://zendesk.com

     Make sure you include the entire URL, including the HTTP or HTTPS format. If you don’t add the entire URL, you’ll get a broken link.

   • To link to a heading in this article, click the Heading tab, then select a heading in the article.

     The title of each heading appears, along with it’s style, so that you know the heading level for each heading in the article.

   • To link to an article in your Help Center, click the Help Center article tab, then select an article title that appears or enter a search for an article, then select an article that appears.

     Click Clear beside the article title if you want to remove the link to an article and select a new article.

4. In Text on link, enter or edit the link text you want to appear in the article.

   If you highlighted text in the article before you click the Link button, the text appears in the field. If you edit the text here, it will update in the article.

5. Select Open in new tab if you’d like the link to open in a new browser tab.

   If the checkbox is not selected, the link will open in the current browser tab, replacing the article.

6. Click Link.

   The link appears in the article.

Editing links in articles

You can edit any existing link in an article to change the text or link target.

To edit an existing link article

1. In Help Center or Guide Admin, open an existing article in edit mode.
2. Highlight the link you want to edit in the article.
3. To change the link text, simply type over the existing text.

4. To change the link target, click Insert/edit link on the editor’s toolbar, then do any of the following:

   • In the URL tab, select the existing URL in the field and paste in a new URL, then click Link.
   • Click the Heading tab, select a heading in the article, then click Link.
   • Click the Help Center article tab, click Clear, if an article is currently selected, and select another article in your Help Center, then click Link

   The link is updated in the article.

Removing links in articles

You can remove a link from text if you want to the text to be plain text and no longer a link.

To remove an existing link in an article

1. In Help Center or Guide Admin, open an existing article in edit mode.
2. Highlight the link you want to remove in the article.
3. Click Insert/edit link on the editor’s toolbar, then do any of the following:

4. Click Remove link at the bottom of the dialog box.

   

   The link is removed from the article.

You can promote articles in a section to draw attention to them. When you promote an article, it moves to the top of the articles list within its section and is usually given a special visual treatment (for example, a star icon).

Promoted articles always appear at the top of the section, regardless of the sorting option chosen. Promoted articles might also appear by default on the home page, depending on your chosen theme.

To promote an article

1. Navigate to the article, then click Edit article in the top menu bar.

   

2. Click Promote article in the article’s sidebar.

   

3. Click Save.

The community consists of posts associated with different discussion topics. Topics can be anything you want, and you can create as many as you want. Guide managers can add, edit, delete, and manually arrange topics. Agents and moderators don’t have the permissions to make these changes.

Editing and deleting discussion topics

You can edit a discussion topic if you need to change the name, description, or access privileges.

You can delete a topic if you no longer need it. When you delete a topic, all the posts in the topic are also deleted. If you don’t want to delete the posts in the topic, move the posts before you delete the topic.

To edit a topic

1. Open the topic in Help Center, then click Edit topic in the top menu bar.

   

2. Make your changes to the name or description and click Update.

For information about managing community posts within discussion topics, see Managing community posts.

To delete a topic

1. Open the topic in Help Center, then click Edit topic in the top menu bar.

   Be sure you’ve moved any posts that you want to save to another topic.

2. Click the Delete topic link on the page.

Reordering discussion topics

You can manually reorder your community discussion topics. You cannot reorder the posts within a topic.

The community consists of posts associated with different discussion topics. Topics can be anything you want, and you can create as many as you want. Guide managers can add, edit, delete, and manually arrange topics. Agents and moderators don’t have the permissions to make these changes.

For information about managing community posts within discussion topics, see Managing community posts.

Adding discussion topics

Discussion topics can be anything you want and you can add as many topics as you need.

For example: if you support multiple products you might add a topic for each product or, if you have one product with a lot of functionality, you might add a topic for each major feature area. You can also add a General Discussion topic where users can discuss issues that don’t quite fit in the other topics.

To add a topic

1. Click Add in the top menu bar, then select Community topic.

   

2. Enter a Name and optional Description for your section.

3. Select a User segment to determine who can access this topic.

   By default, a topic is visible to all users. You can choose to restrict access to signed-in users.

   On Guide Professional and Enterprise, you have the ability to restrict access based on tags, organizations, or groups by applying custom user segments (see Creating user segments to restrict access). On Guide Professional and Enterprise, you can also restrict access to agents and managers to create internal-only access.

4. Under Who can manage posts, select Managers if you want only Guide Managers to add and edit posts, or leave Agents and managers selected if you want agents to also be able to add and edit posts in this section.
5. Click Add.

The community consists of posts associated with different discussion topics. Topics can be anything you want, and you can create as many as you want. Guide managers can add, edit, delete, and manually arrange topics. Agents and moderators don’t have the permissions to make these changes.

Reordering discussion topics

You can manually reorder your community discussion topics. You cannot reorder the posts within a topic.

To manually reorder topics

1. In Guide, click the Arrange content () icon in the sidebar, then click Arrange topics.

2. Click any community topic, then drag it to another place in the order.

   

3. Click Save when you’re finished.

For information about managing community posts within discussion topics, see Managing community posts.

Tags, groups, and organizations are not available on Support Essential. To create user segments, you must have Support Team, Professional, or Enterprise and Guide Professional or Enterprise. If you have Gather Professional, you need Support Team, Professional, or Enterprise and any Guide plan.

A user segment is a collection of end-users and/or agents, defined by a specific set of attributes, used to determine access to Help Center content.

User segments are the building blocks for user permissions. You apply user segments to a knowledge base article or a topic in your community to define viewing access. And you use user segments to build management permissions that you apply to knowledge base articles to define editing and publishing permissions.

There are two built-in user segments by default:

• Signed-in users includes users who are signed-in to your Help Center
• Agents and managers includes all agents and Guide managers

You can create custom user segments to further refine those groups of users as follows:

• Signed-in users (internal and external), based on tags, organizations, or both created in Zendesk Support
• Staff (internal), based on tags, groups, or both created in Zendesk Support

Guide Managers have access to all content, regardless of any user segments they belong to. You must be a Guide Manager to create user segments.

Understanding access restrictions for user segments

Every user segment starts with a base user type of signed-in users or staff (agents and managers). From there, you can create a subset of users based on tags, organizations, and groups, as follows:

• Signed-in users can be restricted by tags, organizations, or both. Tags must be on the user or an organization they belong to.

  When you create a user segment based on tags for signed-in users, you can require that all specified tags match for the agent to be included and/or you can require that at least one of the specified tags match for the user to be included. For organizations, the user must belong to at least one of the specified organizations.

  Signed-in agents must have any required tags, but organization is ignored for agents; agents do not have to belong to any of the specified organizations to be included in the user segment.

• Staff (agents and managers) can be restricted by tags, groups, or both.

  When you create a user segment based tags for staff, you can require that all specified tags match for the agent to be included and/or you can require that at least one of the specified tags match for the agent to be included. For groups, the agent must belong to at least one of the any specified groups.

  Guide Managers have access to all content, regardless of the user segments they belong to.

You can define user segments as shown in the following table.

Creating user segments

There are two access types for user segments: signed-in users and staff.

You can create custom user segments to further refine those groups of users as follows:

• Signed-in users (internal and external), based on tags, organizations, or both created in Zendesk Support
• Staff (internal), based on tags, groups, or both created in Zendesk Support

You can create as many as 200 user segments per account. If you have multiple brands in your account, your user segments are shared across all brands.

Guide Managers have access to all content, regardless of any user segments they belong to.

To create a user segment

1. In Guide, click the User permissions icon () in the sidebar.

2. On the User Segments page, click Add new.

   If you receive an error message, then you have reached your maximum number of 200 user segments. You can delete some user segments if you want to continue.

3. Enter a Name for this user segment.

4. Select a User type as the base of your user segment.

   • Signed-in users include internal and external users who create an account and sign in to your Help Center.
   • Staff are internal users only, including agents and Guide managers.

   

5. Click Next.

6. Click Add tag, then click the drop-down menu to select a tag.

   • If you add tags under Users and organizations matching all of these tags, all of the tags must be on the user or org to be included in the user segment.
   • If you add tags under Users and organizations matching any of these tags, one or mor of the tags must be on the user or org to be included in the user segment.

   You can add up to 50 tags in Users and organizations matching all of these tags and up to 50 tags in Users and organizations matching any of these tags.

   You can search or scroll to find tags. Note that not all available tags appear in the list. You can choose any tag that is applied to existing users or organizations. The tags can be on the user profile or, for end-users, inherited through an organization.

   A list of matching users appears below. Any agents with the tag will belong to the user segment, but agents do not appear in the matching list.

   You must have user tags enabled to create a user segment based on tags (see Enabling user and organization tagging).

7. If you want to add multiple tags, click Add tag again, then select a tag.

8. You can further refine your user segment by doing one of the following:

   • For signed-in users, click Add organization if you want to restrict by org, then click the drop-down and select an org.
   • For staff members, click Add group if you want to restrict by group, then click the drop-down and select a group.

   The user must belong to at least one of the organizations or groups to be included in the user segment. The exception is that organization is ignored for signed-in agents. Agents do not need to belong to any of the organizations to be included in the user segment.

   The list of matching users updates, but, remember, agents do not appear in the matching list.

9. Click Save.

   You can apply user segments to:

   • Set view permissions on knowledge base articles
   • Create management permissions to define agent editing and publishing rights
   • Set view access for community topics

By default community discussion topics are visible to all users. You can prevent some users from viewing the content of certain topics.

You can configure a topic to restrict access to signed-in users or to agents and managers. You can also apply custom user segments you’ve created to further restrict access based on tags, organizations, or groups (see Creating user segments to restrict access).

You must be a Guide Manager to set access restrictions for community topics. Viewing restrictions do not apply to Guide Managers. Managers can access all topics in the community, regardless of the restrictions.

To restrict access to a community topic

1. Navigate to the topic in the community that you want to restrict.

2. Click Edit topic in the top menu bar.

   

3. Select a User segment to determine who can access this section.

   You can choose to:

   • Restrict access to signed-in users
   • Restrict access to agents and managers to create internal-only access
   • Restrict access based on tags, organizations, or groups by applying a custom user segment (see Creating user segments to restrict access)
4. Click Update.

To set access restrictions in the knowledge base, see Setting view permissions on articles with user segments.

When you first launch a community with Gather, we recommend that you follow some basic steps and enable certain features to help you to guide your users and make managing your community easier.

Writing a community code of conduct

Before you launch your community, it’s important to write down what the rules of the space will be. This helps users to understand how to participate in your community, and what kinds of things won’t be allowed.

In addition to letting users know the things you might not want them to do in the community, for example, posting spam or harassing others, also consider things like:

• Is it ok for people to promote their business or solicit other users to contact them outside of your site?
• Are there terms, phrases, or certain kinds of activity that will not be allowed in your community?
• If a user violates any of the rules, how will they be enforced? It’s good to explain to users what will happen if they violate the code of conduct.

Post the code of conduct in your community, and consider pinning it to the top of a topic. It should be easy for users to find and refer to.

It’s important to revisit your code of conduct regularly, and make adjustments to the rules as required. If you have a legal team as a part of your organization, you might want to include them in the process or get their approval.

Here’s the Zendesk Community Code of Conduct as an example.

Setting up content moderation filters

We recommend using the content moderation feature to help avoid spam and other inappropriate or abusive posts being published in your community.

You can choose whether you want to moderate all posts, or just those matching certain keywords. You’ll need to evaluate which option will be best for your community, depending on the kind of audience you’ll be engaging, the size and capabilities of the team you have managing your community, and how much of a risk is posed by spam in your community.

Moderating all posts can be very effective in eliminating any spam from getting through. However, it is best to use this feature only if you have a team that can be highly responsive in approving posts (that is, they can log in and approve content whenever a notification is received, or periodically during your community’s most active hours), or if your community is one that does not require speedy responses. This is because when the content is pulled into the moderation queue, the user has to wait for a Guide Manager to approve the post before it goes live, which can lead to a significant lag between when a user tries to make a post and when it actually appears in the community.

Using the keyword function allows you to specify words that, when they’re present in a post, trigger the post to go into the moderation queue to be reviewed, and then either approved or rejected by a Guide Manager. This means that posts without any of the keywords are published immediately, which is preferable for a community trying to foster high conversational engagement. However, this option does run the risk of allowing some spam posts through on occasion, until the spam filter learns or a new keyword is added to the filter.

See moderating end-user content to learn more about content moderation for your Help Center.

Creating moderator groups and setting permissions

The community moderator feature enables you to assign certain permissions to groups of users (agents and end-users) so that they can assist your community managers to moderate the community.

This feature is not available with Gather Legacy. See About Gather plan types.

Identify a group of trusted users or agents, and give them the ability to flag posts for moderation, so that they can help hide anything that shouldn’t be in your community or flag questionable content for your community managers to review.

There are a variety of permissions that you can give to these groups, and you can set up multiple groups with different sets of permissions. To learn more, see creating community moderator groups.

Creating your first few topics

Start by creating two or three topics in your community. More than three topics can spread your users across too many spaces, especially when launching a new community.

To determine what your initial topics should be, you should consider:

• Your goals for the community
• What your customers or users are most interested in talking about

It can be helpful to look at support tickets that you already receive. See what areas come up most often, then create a topic in your community for users to discuss that topic. Your topics should be specific enough that users know what they’re supposed to do when they get there, but broad enough to apply to a wide variety of users.

Fill in the description field for your topics, to help users understand what they’re supposed to post.

Writing pinned “how to” and welcome posts in each topic

In addition to the topic description, it is helpful to write a pinned post to explain to users what the space is for and how to best use it. If the code of conduct tells your users what not to do, this post tells them what you do want them to do.

This step is especially helpful if you want to encourage users to post in a specific format, include specific information in their post, or use voting in a specific way.

For example, your topic might be set up for users to share recipes. You want them to follow a format of listing the ingredients first and the recipe instructions second. You might also want them to vote on their favorite recipes. While this might seem intuitive, it will be helpful to explain what you want them to do.

Another example might be collecting product feedback, where you want to encourage users to post which version of a product they’re using and answer some specific questions in their post.

Here are some examples from the Zendesk Community, explaining to our users how to participate in different topics:

• How to ask a question in the Zendesk Community
• How to write an effective feedback post

Customizing your theme

As a bonus, consider customizing your community’s theme to make your new community’s look and feel match the rest of your website or brand. A common theme can help your users feel more at home and connected to the other ways they connect with your organization online.

The Zendesk Guide theme is highly customizable. There are a number of free and paid themes available in the Zendesk Marketplace, or you can contact a Zendesk partner to assist in building a custom theme.

More community resources

If you have any questions about any of these recommendations, from writing your code of conduct to determining which kind of content moderation to use, or on setting up your moderator permissions, you can connect with Zendesk Gather experts in the Zendesk Community.

Ask any questions specific to setting up or launching your community in the Gather Q&A topic.

You can edit, move, or delete community posts, as well as edit or delete comments on community posts. You can also take a number of actions on the post or comment.

The user interface described in this article is based on the default Copenhagen theme. If your theme is customized, options might appear differently or be missing.

Guide Managers have full permissions to manage community posts. Users with moderator rights can perform a limited number of actions on posts depending on their moderator group permissions. Regular agents, who are not part of a moderator group, don’t have permissions to take any actions on community posts.

For information about managing the discussion topics that contain community posts, see Managing Help Center community discussion topics.

Editing and deleting community posts

You can edit or delete community posts as needed.

To edit a post

1. In the post you want to edit, click the Post actions icon (), then select Edit.

   

2. Make your changes, then click Update.

To delete a post

1. In the post you want to delete, click the Post actions icon (), then select Delete.

2. Click Ok to confirm the deletion.

   The post is removed from the topic and cannot be recovered.

Editing and deleting comments on community posts

You can edit or delete comments on community posts as needed.

You can also mark a comment as official (see Marking a comment as the official comment for a post).

To edit a comment

1. Beside the comment you want to edit, click the options menu, then select Edit.

   

2. Make changes, then click Update.

To delete a comment

1. Beside the comment you want to delete, click the Comment actions icon (), then select Delete.

   The comment is removed from the post and cannot be recovered.

Moving a post to another discussion topic

You can move a post from one discussion topic to another in your community. You cannot move a community post to the knowledge base.

To move a post to another topic

1. In the post you want to move, click the Post actions icon (), then select Edit.

   

2. Click inside the Topics box and select another topic.
3. Click Update.

Promoting a post by pinning or featuring

You can promote community posts by pinning or featuring.

When you pin a post, it moves to the top of the posts list within its topic and has a star beside it. This enables you to draw attention to important posts in a topic, such as announcements or guidelines.

Pinned posts always appear at the top of the topic, regardless of any sorting option chosen. The most recently pinned post will be the top-most. You can manually add styling for pinned posts so that they appear different than other posts in the topic.

When you feature a post, it is labeled as “featured” and appears in the featured posts component, which you can add to any page in your theme.

To pin a post

• In the post you want to pin, click the Post actions icon (), then select Pin to top.

If you don’t want the post to be pinned to the top of the topic anymore, select Unpin from top.

To add styling for pinned posts to your theme

1. In Guide, click the Customize design () icon in the sidebar.
2. In the Theme panel, click Edit theme.
3. Select the Community post page in the template drop-down in the upper-left.
4. Click Post actions.
5. Click Pin to top.

6. Click the CSS tab, then add the following CSS to style pinned posts or modify it to fit your design:

    .post-pinned .question-title:before {
      content: "\2605";
      margin-right: 5px;
      color: $color_5;
    }
   

7. Click Save, then Publish changes.

To feature a community post

• In the post you want to feature, click the Post actions icon (), then select Feature post.

  

You must have added the featured posts component to your theme for the post to be featured. Otherwise, selecting the feature post option does nothing.

If you don’t want the post featured in the Featured Posts component anymore, select Unfeature post.

To add featured posts to your theme

1. In Guide, click the Customize design () icon in the sidebar.
2. In the Theme panel, click Edit theme.

3. Select a template from the template drop-down in the upper-left, then paste the following snippet of code where you want featured posts to appear (on your Home page, for example).

    <div class="featured-posts">
      <h2>
        {{t 'featured_posts'}}
      </h2>
      {{#if featured_posts}}
        <ul class="featured-post-list">
          {{#each featured_posts}}
            <li>
              <a href="{{url}}">{{title}}</a>
            </li>
          {{/each}}
        </ul>
      {{else}}
        <p>
          {{t 'no_featured_posts'}}
        </p>
      {{/if}}
    </div>
   

4. Click Preview at the top to ensure it looks as intended. To preview a featured post, use the preview window to the right of the theme editor, locate a post, click Post actions and click Feature post.
5. Click Save, then Publish changes.

Setting status for a community post

You can set a status of Planned, Not planned, or Completed on any community post. This can be especially useful if you have feature requests in your community and want to communicate status.

When you set status, the status appears in the list of posts within the topic and on the post itself. You can filter by any status to see all posts in a topic with the selected status.

To set status on a community post

• In the post where you want to set status, click the Post actions icon (), then select one of the statuses: Planned, Not planned, Completed, and Answered.

To filter community posts by status

• In a community topic, click Show all, then select one of the status options.

Closing a post for comments

If you don’t want to allow comments on a community post, you can close the post for comments.

To close a community post for comments

• In the post you want to close for comments, click the Post actions icon (), then select Close for comments.

Marking a comment as the official comment for a post

You can mark a comment as the official comment for a community post. You can make either a new comment or an existing comment the official comment. Make sure that you mark only one comment as the official comment for a post. You cannot mark an official comment on a knowledge base article.

When you mark an official comment, it appears as the first comment on the post and is indicated as the official comment. That means that if you edit an existing comment and mark it as official, that comment moves from its current place in the order and timeline of comments, and appears at the beginning, ahead of any older comments.

If a comment is marked as the official comment and the user who made the comment is downgraded to end user, the comment remains the official comment.

To mark a comment as the official comment

1. In the post where you want an official comment, either enter a new comment or edit an existing comment.

2. Click Official comment under the comment.

   

3. Click Submit or Update, depending on whether you are making a new comment or editing an existing comment.

   The comment becomes the first comment on the post and is indicated as the official comment. The official comment checkbox is then hidden for all other comments related to the post.

Marking a post as answered

If a comment has been added that answers the subject of a post, you can mark the post as answered.

To mark a post as answered

• In the post you want to mark as answered, click the Post actions icon (), then select Answered.

  If you have the correct moderator permissions, you can set the status as Answered only if a status has not previously been set.

  If you are a Guide Manager, you can change the status to Answered from any other state.

Approving pending content

If a post or comment is marked as pending approval, you can mark it as approved.

To mark a post as approved

• In the post you want to mark as approved, click the Post actions icon (), then select Approve.

This action is not available for content that is pending approval in the spam queue.

Moving a live community post to the moderation queue

You can send a live post to the content moderation queue if it contains content that you want to review. The post is then hidden from the community and appears in the content moderation queue for Guide Managers.

To move a live post for moderation

• In the post you want to moderate, click the Post actions icon (), then select Hide for moderation.

The post is no longer visible to the community, however Guide Managers can see the post in the content moderation queue. From there, a Guide Manager can review the post and decide which action to take. See Moderating end-user content.

Creating a ticket from a community post or comment

You can create a ticket from a community post or comment. When you do, a ticket is created in your instance of Zendesk Support with the body text from the post or comment and a link to the post or comment.

In the community post, the ticket number link appears at the top of the post so you can easily access the ticket from the post. In a community comment, the ticket number link appears beside the comment. If you click the link, you can access the ticket directly.

To create a ticket from a community post

1. In the post you want to convert to a ticket, click the Post actions icon (), then select Create a ticket.

2. A Create a ticket window appears with the following fields pre-filled with information from the post:

   • Subject:

     Request created from: <community post title>

   • Description:

     This request was created from a contribution made by <post creator name> on <date and time>.

   There is a link to the post itself, followed by the post contents.

   • Who should be the requester of the ticket?:

     The default ticket requester is the person who created the post, but you can change this to be yourself. The person specified in this field receives an email notification when the support ticket is created.

   

   Make any changes to the subject or description as needed, then select yourself or the poster as the requester of the ticket.

   The person specified in this field receives an email notification.

3. Click Create ticket.

4. In Support, the ticket is created, and is triaged by your support team.

   

To create a ticket from a comment on a community post

1. Beside the comment you want to convert to a ticket, click the Comment actions icon (), then select Create a ticket.

   

2. A Create a ticket window appears with the following fields prefilled with information from the comment:

   • Subject:

     Request created from: <community post title>

   • Description:

     This request was created from a contribution made by <comment creator name> on <date and time>.

   There is a link to the comment itself, followed by the comment contents.

   • Who should be the requester of the ticket?:

     The default ticket requester is the person who created the comment, but you can change this to be yourself. The person specified in this field receives an email notification when the support ticket is created.

     

   Make any changes to the subject or description as needed, then select yourself or the poster as the requester of the ticket.

   The person specified in this field receives an email notification.

3. Click Create ticket.

4. In Support, the ticket is created, and is triaged by your support team.

   

The community features are wonderful, especially the post actions. However, what happens when the default actions aren’t exactly what you are looking for? Currently there is no way to add or modify the actions that are available, but with Curlybars the existing actions can be re-purposed.

Displaying new status icons

For the purpose of this article, let’s say we want to change the actions from: Planned, Not Planned, Completed and Answered to In the Works, Under Construction, Implemented and Officially Answered. To make these modifications, the replacement text will need to be inserted in all of the affected pages. To learn more about how to use Curlybars to make these changes, see Enhanced Help Center theming framework.

The image below displays what the original statuses look like:

The image below displays what the new statuses will look like:

There are two steps to change all customer facing instances to the desired replacement name:

1. Modifying ‘Show all’
2. Changing status icons’ names

Modifying ‘Show all’

1. In the Help Center, Edit your theme code. For more information on how to edit a Help Center theme, see Customizing your Help Center theme.
2. Select the community_topic_page.hbs as the template to edit.

3. Locate the code for the filter labels inside the dropdowns:

   

4. Modify the {{#each filters}} with the following ‘identifier’ information:

    {{#each filters}}
     <a href="{{url}}" aria-selected="{{selected}}" role="menuitem">
      {{#is identifier 'all'}}{{name}}{{else}}
      {{#is identifier 'not_planned'}}Gathering Feedback{{/is}}
      {{#is identifier 'planned'}}In the Works{{/is}}
      {{#is identifier 'answered'}}Officially Answered{{/is}}
      {{#is identifier 'completed'}}Implemented{{/is}}
      {{/is}}
     </a>
    {{/each}}
   

5. Click Publish.

Changing status icons’ names

The next change you need to make is for the actual status icons on the Community topic page. Your updated status icons will resemble the image below.

1. Scroll down to the {{#is status 'none'}} expression lower on the Community topic page.

2. Enter the following code to change your status icons:

    {{#is status 'none'}}
     {{else}}
      <span class="status-label-{{status_dasherized}} status-label striped-list-status">
      {{#is status 'not_planned'}}Gathering Feedback{{/is}}
      {{#is status 'planned'}}In the Works{{/is}}
      {{#is status 'answered'}}Officially Answered{{/is}}
      {{#is status 'completed'}}Implemented{{/is}}</span>
    {{/is}}
   

3. Click Publish.
4. Next, select the community_post_list_page.hbs template and locate the same {{#is status 'none'}} expression.
5. Enter in the above code there as well.

6. You have successfully modified your list pages and drop-downs. The only thing left to do is make sure the status indicator on the individual posts reflect the correct wording as shown in the screen shot below.

   

7. Select the community_post_page.hbs template to modify individual posts.

8. Enter the following code on the {{#if post.status}} expression:

    {{#is post.status 'none'}}
      {{else}}
      <span class="status-label-{{post.status_dasherized}} status-label">
      {{#is post.status 'not_planned'}}Gathering Feedback{{/is}}
      {{#is post.status 'planned'}}In the Works{{/is}}
      {{#is post.status 'answered'}}Officially Answered{{/is}}
      {{#is post.status 'completed'}}Implemented{{/is}}
      </span>
     {{/is}}
   

   

9. Click Publish.

Using dynamic content to translate your statuses

If your Help Center is available in multiple languages you can use dynamic content helpers to translate your new terms. For more information on dynamic content see, Dynamic content helpers and Providing multiple language support with dynamic content.

You can create the dynamic content in Zendesk Support and then use the helpers below in place of the previous term.

This will enable your status icons to translate for your many customers.

Now that all of your bases are covered, all end-user information should display your own words, and not the default options provided with the feature!

Guide managers can see all community activity in moderation activities.

This is a view of all actions taken by community moderators, as well as any actions taken by the community itself. For example, you can see if posts have been approved or featured by community moderators, or if someone has moved or deleted their own post. If you haven’t set up any community moderators yet, see Creating community moderator groups.

Moderation activities is a historical record of activity in the community. If you want to change any of the actions applied to a particular post or comment, you need to do that in the post or comment itself.

To view moderation activities

1. In Guide, click the Moderate content () icon in the sidebar.

2. Click Moderation activities. The Moderation activities page appears.

   

   You can see all the actions that have occurred in the community, including information on the event, the relevant article or comment, who moderated the content, and the date of the activity. You can sort events by date.

   • Event: shows the actions taken for a post or comment.

     These actions might include Hide for moderation, Approve, Pin to top, Feature post, and Mark as answered. See Managing community posts for all actions you can take on a post or comment.

     If a post has been moved, hover over the post and you can see information about the original location and the new location of the post.

   • Content: shows the post or comment that has been actioned.

     Click the text in Content to go to the post or comment.

     If a moderator hides a post or comment, and then deletes it, there is not a link to the content because the content has been permanently removed from the community.

   • Moderated by: shows the avatar of the moderator.

     Hover over the image to see the name (or alias) and role of the moderator.

   • Date: shows the date of the action.

     You can sort the events in ascending or descending date order.

You can monitor activity data for your community using in the Reporting dashboard in Support. Statistics include the number of posts created, how many users have viewed posts, and the total number of votes, subscriptions, and comments.

You must be a Guide Manager to view these statistics. To view knowledge base activity, see Analyzing knowledge base activity.

You must enable your Help Center and community before you can view the Community dashboard (see Getting started with Gather).

Viewing community activity for your Help Center

You can view community analytics for your Help Center in the Reporting dashboard in Support.

To view community data

1. In Support, click the Reporting icon () in the sidebar, then click the Community tab.

The Posts dataset is open by default.

1. If you have multiple brands, click the All brands drop-down menu, then select a brand if you want to see data for that brand only.

   All brands is selected by default, and includes the combined activity of the communities in all of your Help Centers.

2. Click the Reporting period drop-down menu, then select an option if you want to change the reporting time frame.

   Select Custom to enter a specific start and end date.

3. Click any of the five datasets at the top to drill down.

   Each dataset displays a graph of daily activity and a table, below the graph, of top posts for that dataset. Datasets include:

   • Posts is the total number of new posts created in the community during the reporting period.
   • Views is the total number of views for posts in the community during the reporting period, including internal agent views.
   • Net Votes is the difference of all the positive and negative votes on all posts in the community during the reporting period.
   • Subscriptions is the total number of user subscriptions for topics and posts in the community during the reporting period.
   • Comments is the total number of comments on posts in the community during the reporting period.

4. Hover your mouse over a node to see the total number for that day.

   

Following up on community data

Community statistics give you insight into which questions customers are most interested in. You can then take action based on this information.

For example, you can track the posts that are most and least popular, or have the most comments, to understand more about the subject. You can then review the post to see if there is some follow up action required, for example, whether this area requires a knowledge base article to explain the subject in more detail, or a ticket needs to be raised to request a new feature.

On Guide Professional and Enterprise, agents can use the Knowledge Capture app in the Support agent interface to create new articles using pre-defined templates. If a template does not exist, agents will not be able to create articles using the Knowledge Capture app.

The agent can copy and paste content from the ticket, or write new content based on the ticket, to create the article. The Knowledge Capture app does not pre-populate the new article with content from the ticket.

For information about planning your workflow, see Setting up your workflow for created articles.

If you do not want agents to create articles using the Knowledge Capture app, you can disable that option.

To create an article

1. In a new or existing ticket, open the Knowledge Capture app.

   You must open the ticket directly. You cannot use the Knowledge Capture app when you select a ticket in a view and click the Edit ticket(s) button.

2. Click the Create Knowledge button in the Knowledge Capture app.

   

3. If you have multiple brands, click the drop-down menu to select a Help Center.

4. Select a template from the list.

   Agents can see and select only the templates where they have management permissions for editing.

   If you have not created any templates, you need to set up a template first (see Creating templates for the Knowledge Capture app).

   

5. Add a title and content to the article, according to the headings in the template.

6. Change the article’s section, if necessary, depending on your workflow for new knowledge.

7. Make any other changes you need in the article’s sidebar.

   The author is automatically updated to be the agent creating the article.

8. Click Save or choose another option from the drop-down.

   The article created is a duplicate of the template; it does not overwrite the template. The new article does not retain the KCTemplate label.

The Knowledge Capture app is installed by default with any Guide plan and Support Team, Professional, or Enterprise.

The app enables agents to:

• Search the Help Center without leaving the ticket
• Insert links to relevant Help Center articles in ticket comments
• (Guide Professional and Enterprise) Add inline feedback to existing articles that need updates
• (Guide Professional and Enterprise) Create new articles while answering tickets, using a pre-defined template

The Knowledge Capture app is available in the Zendesk Marketplace if it does not appear in your Support agent interface (see Opening the Knowledge Capture app) or you need to install it again for some reason.

You cannot install the Knowledge Capture app on Support Essential.

To install the Knowledge Capture app

1. In Zendesk Support, select Admin > Apps > Marketplace, then find the Knowledge Capture app and click the icon..

   

2. Click Install.

3. On the Installation page, enter a new Title, if you’d like.

4. Select or deselect any of the app settings, as needed:

   • (Guide Professional and Enterprise only) Allow agents to create new articles enables agents to use the app to create new articles using a pre-defined template (see Creating articles with the app).
   • (Guide Professional and Enterprise only) Allow agents to flag articles enables agents to use the app to identify existing articles that need updates and add inline comments (see Flagging articles with the app).
   • Show in ticket editor shows the app in the ticket editor. You can choose to display the app in both the editor and the apps panel.

   For tickets from social channels or markdown tickets where the rich text editor is not available, the app will be available in the sidebar app location.

   • Show in the Apps panel shows the app in the apps panel in the ticket sidebar.
   • Auto-select brand for search enables the app to search the Help Center of the brand set on the ticket. When deselected, the app searches the Help Center based on the agent’s last selected brand in the Knowledge Capture app.

5. Click Enable role restrictions if you’d like to limit app access to specific roles, then select a role.

   You can select multiple roles.

   

6. Click Enable group restrictions if you’d like to limit app access to specific groups, then select a group.

   You can select multiple groups.

7. Click Install.

   The Knowledge Capture app is added. To start using the app, see Opening the Knowledge Capture app.

Agents can use the Knowledge Capture app to create new articles for Help Center, directly from the Support ticket interface. To do so, you need to create one or more templates for your agents to use to create their new content.

Any article in your Help Center that contains the label KCTemplate is available as a template in the Knowledge Capture app. You can create as many templates as you need. If you have multiple brands, you must create a template in each Help Center.

Here’s how it works when an agent uses the app to create new content based on a template:

• Any new article created using a template is a duplicate of the template and does not overwrite the template article.
• All of the template’s fields are duplicated for the new article, with two exceptions: the KCTemplate label is removed and the author is set to the user creating the new article.
• All of the template’s content is duplicated for the new article except for images or attachments, which are not included in any new article.
• The section where the template is published is retained for the new article. Agents can manually change the section, if they want, to any section where they have permission to publish.

You must install the Knowledge Capture app (see Installing the app) and have Guide Professional to create templates and articles using the app.

To create a template for the Knowledge Capture app

1. Click Articles in the top menu bar, then select Add article.

   Alternatively, you can open an existing article that you want to make a template.

   

2. Enter a Title for your template.

   Think about the types of templates you plan to create and consider including the type in the title. For example, you might want to create a Q&A template and a How To template, and include that in the template title.

3. Enter the headings and content for your template in the body.

   You might want to include headings specific to the type of template you are creating. For example, a Problem/Solution template might include sections for the problem, the conditions, and the steps for the solution.

   Check out this discussion for template ideas: Do you use a template to author your knowledge base content.

   Do not include images or attachments, as they will not be included in any new article created based on this template.

4. Set the Managed by and Visible to permissions.

   Agents will only be able to use templates where they have management permissions for editing.

5. In Publish in section select a section for the template.

   You might want to create a restricted Help Center section for agents to publish new content, depending on your workflow. Alternatively, you might want agents to create new content as a draft or work in progress.

   New articles based on this template will be created in the section you specify, unless an agent manually changes the section. Agents can create new articles in any section where they have permission (see Allowing agents to add, edit, and delete articles). The template does not restrict agents to publishing in a specific section.

6. Leave the Author as is.

   When an agent creates an article based on this template, the current agent will be set as the author automatically.

7. Add KCTemplate in Label.

   The label will not persist on any new articles created based on the template.

   You must add this label for your article to be treated as a template in the Knowledge Capture app.

8. Click Save.

   Now your template will be available to agents using the Knowledge Capture app to create new articles. For information, see Creating articles with the Knowledge Capture app.

Agents can use the Knowledge Capture app in the Support agent interface to search for Help Center articles and preview them, without leaving the ticket. They can also add a link to the article directly in the ticket.

Searching for and previewing articles

You can use the Knowledge Capture app to search the Help Center for articles relevant to the issues raised in the ticket. The Knowledge Capture app search uses the same search technology as the Help Center search.

The app searches content in the end-user’s selected language, if it’s available in your Help Center. Otherwise the app searches the default language of your Help Center. You can change the language in the app to search another language in your Help Center.

If you have multiple brands, the app searches the Help Center associated with the brand of the ticket. You can change the brand to search Help Center content for another brand.

To search for Help Center articles

1. In a new or existing ticket, open the Knowledge Capture app.

2. Enter a topic or keyword in the Knowledge Capture app search box.

   On Lite, the search results are pre-populated based on a search of the ticket subject. On Professional and Enterprise, the search results are pre-populated with Answer Bot-powered article suggestions, based on the requester’s most recent comment.

3. Press Return or click the Search icon.

   The search returns public and internal articles. The search does not return other content, such as drafts or community posts. Internal articles indicate that they are locked and not available to the requester.

4. To open a preview of the article in a preview window, click an article card.

   If you’re using the app in the ticket editor location, you can hover over an article card to see a preview in the app. There is not a hover preview if you’re using the app in the Apps panel sidebar location.

   

5. If you support multiple brands and languages, click the brand or language or brand drop-down to change the selection for your search.

   By default, if you support multiple languages, the app searches content in the end-user’s selected language, if available; otherwise the app searches the default language of your Help Center. By default, if you support multiple brands, the app searches content the Help Center associated with the brand of the ticket you are viewing. You can change the language and the brand in the app.

   

Adding links to articles in tickets

When you find an article you think is useful in the app search, you can add a link to it in the ticket. You can add link to multiple articles in a comment.

Any link in a ticket comment is recorded by the Knowledge Capture app, regardless of whether it was added manually or using the app. If you want to add a link to an internal article that the requester does not have permission to view, you can add it in an internal comment and it will be recorded as Knowledge Capture.

If you are on Guide Professional or Enterprise, links to articles in tickets are recorded as events in the Knowledge Capture dashboard (see Analyzing your Knowledge Capture activity).

To add a link to an article

1. In a new or existing ticket, open the Knowledge Capture app.

   You must open the ticket directly. You cannot use the Knowledge Capture app when you select a ticket in a view and click the Edit ticket(s) button.

2. Review the pre-populated results or enter your own search and review the results.

   On Lite, the search results are pre-populated based on a search of the ticket subject. On Professional and Enterprise, the search results are pre-populated with Answer Bot-powered article suggestions, based on the requester’s most recent comment.

3. If you support multiple languages or brands, click the language or brand drop-down in the app to change the language or the brand for your search.

4. To insert a link to an article, do one of the following:

   • Click Link article in the article card.

   

   • Click Link article in the article preview modal.

   

   • (Editor app location only) Click Expand article in the article preview, then select Link article.

   

   When you link to an article, the hyperlink is inserted in the comment where your cursor is. The link is host mapped, if you have host mapping.

   If you have WYSIWYG enabled, the link text inserted is the article title, linked to the article in Help Center. If you have Markdown enabled, the markdown {{Article title}}: {{URL}} is inserted.

5. To remove the link or to modify link text in the comment, click the link in the comment, then click the Delete icon or the Edit icon.

   You can only do this before the comment is submitted. You cannot remove a linked article after the comment has been submitted.

   

6. Add any other text you’d like to the comment, then submit the ticket as you normally would.

   On Professional and Enterprise, the ticket requester has the option to self-solve the ticket if the linked article solves their issue, unless that setting has been disabled.

   A comment is added to the ticket if the requester solves the ticket. It will either be a comment from Answer Bot or Rapid Resolve, depending on whether the linked article was an Answer Bot suggestion or an article you manually found and inserted.

About the user experience with Answer Bot

On Guide Professional and Enterprise, when agents use the Knowledge Capture app to search and link to articles, Answer Bot automatically suggests articles, based on a number of criteria including the ticket subject and requester’s most recent comment. This functionality is built-in, and does not require an Answer Bot subscription.

Answer Bot suggested articles in the Knowledge Capture app are indicated by the Answer Bot logo and name on the article.

Answer Bot only works in certain languages (see Answer Bot supported languages).

By default, when an agent uses the Knowledge Capture app to link to an article, either an article suggested by Answer Bot or an article the agent manually finds and links to, the ticket requester has the option to solve the ticket after viewing the linked article.

When the user opens the linked article, they can click “Yes, close my request” if the article resolves their issue, and the ticket is solved. The user can click “No” if the article does not resolve their issue, and the ticket status is unchanged.

Back in the ticket the agent can see that the user self-solved the ticket.

• If the article was suggested by Answer Bot, the ticket comment is from Answer Bot.

  

• If the article was manually found and linked to by the agent, the ticket comment is from Rapid Resolve.

  

On Guide Professional and Enterprise, agents can use the Knowledge Capture app in the Support agent interface to add feedback to flag existing articles. If a ticket reveals missing or incorrect information in an article, an agent can add a comment near the relevant text describing the needed change to flag the article for an update.

When an agent submits feedback for an article, a ticket is created. The ticket includes:

• A link to the article that needs the update
• A link to the ticket that is the source of the update
• The user name of the agent who flagged the ticket
• The inline comments added by the agent

For information about planning your workflow, see Setting up your workflow for flagged articles. If you do not want agents to flag articles using the Knowledge Capture app, you can disable that option.

To flag an article

1. In a new or existing ticket, open the Knowledge Capture app.

   You must open the ticket directly. You cannot use the Knowledge Capture app when you select a ticket in a view and click the Edit ticket(s) button.

2. Click an article title in the search results in the app to open the article in a preview window.

   You might need to search first if you don’t see the article you want to flag.

3. Hover over the text that needs an update, then click the comment icon that appears beside the text.

   

   A comment field appears.

4. Enter your feedback in the comment field.

   If you need to remove your comment, click the X beside the comment field.

5. Add comments to other sections, as needed.

6. Click Send feedback.

   You will not see the feedback button until you have entered at least one comment.

When you submit feedback, a new ticket is created. The link to the ticket appears at the top of the feedback window.

The resulting flagged ticket has the tag knowledge_capture_flagged_article. You can use the tag to create views, macros, and business rules.

The resulting flagged ticket contains a link to the original ticket where it was flagged, if the article was flagged from an existing ticket. If the article was flagged from a new ticket, that had not been submitted yet, the resulting flagged ticket will not have a link to the original ticket because the new ticket did not have a ticket number at the time.

Agents can open the Knowledge Capture app in the Support agent interface to perform the following actions:

• Search the Help Center without leaving the ticket
• Insert links to relevant Help Center articles in ticket comments
• (Guide Professional and Enterprise) Add inline feedback to existing articles that need updates
• (Guide Professional and Enterprise) Create new articles while answering tickets, using a pre-defined template

The Knowledge Capture app appears in the editor toolbar in tickets by default with any Guide plan and Support Team, Professional, or Enterprise. It might appear in the editor toolbar in tickets, in the Apps panel in the sidebar, or in both locations, depending on how it’s set up.

If the you do not see the see the Knowledge Capture in any of those locations, you might need to have an admin manually install the app (see Installing the Knowledge Capture app). You cannot install the Knowledge Capture app on Support Essential.

Opening the Knowledge Capture app from the editor toolbar

Agents can open the Knowledge Capture app from the editor toolbar in tickets, if it appears there. The Knowledge Capture app appears in the editor toolbar in tickets by default.

To open the Knowledge Capture app from the editor toolbar

1. Open a new or existing ticket.

   You should not open the ticket by selecting it in a view, then clicking the Edit ticket(s) button. The Knowledge Capture app is not available in that case.

2. Click the Knowledge Capture icon in the editor toolbar under the ticket comment.

   

   The Knowledge Capture app opens. The Knowledge Capture app will not load if you have not activated your Help Center.

You can use the Knowledge Capture app to take the following actions:

• Add links to articles in tickets
• Add feedback to flag existing articles (Professional and Enterprise)
• Create new articles based on tickets (Professional and Enterprise)

Opening the Knowledge Capture app from the Apps panel in the sidebar

Agents can open the Knowledge Capture app from the App panel in the sidebar, if it appears there. An administrator must enable the app in the sidebar location. It does not appear there by default.

To open the Knowledge Capture app from the Apps panel

1. Open a new or existing ticket.

   You should not open the ticket by selecting it in a view, then clicking the Edit ticket(s) button. The Knowledge Capture app is not available in that case.

2. Click the Apps button to open the Apps panel, if it’s not already open.

3. Locate the Knowledge Capture app.

   

   The Knowledge Capture app will not load if you have not activated your Help Center.

You can use the Knowledge Capture app to take the following actions:

• Search existing articles
• Add links to articles in tickets
• Add feedback to flag existing articles (Professional and Enterprise)
• Create new articles based on tickets (Professional and Enterprise)

How does Answer Bot process natural language?

Answer Bot is powered by Artificial Intelligence which means that it is able to mimic human behavior. Answer Bot uses natural language processing (NLP) to read every article in your help center and to understand the main concept behind each article. Answer Bot then takes all the concepts from all the articles and places them onto a map. Each concept gets its very own “address” on the map so that it lives near other, similar concepts. However, instead of just city, street, and zip code, this address has 500 parts. Whenever a new question comes in, Answer Bot does its best to understand the concept that the question is asking about and use the map to determine the closest existing article.

For example, here are some concepts that Answer Bot might extract from a few questions:

How does Answer Bot decide which articles to recommend?

When an incoming question closely matches with an existing article, they become “neighbors” on the map (as described above) and it’s clear that Answer Bot should recommend the article. However, when the closest match is a few streets over, or in a nearby neighborhood, it becomes less certain that the concepts are related.

The data science team at Zendesk carefully monitors Answer Bot’s performance and has finely tuned this over time by adjusting a “threshold knob”. This threshold is not adjustable by admin or agents, it’s only accessible to the Zendesk development teams. The threshold knob is a global control, meaning it affects all Answer Bot accounts, and is used to determine how closely two concepts must be on the concept map to be considered similar concepts. If the threshold knob is turned up, Answer Bot becomes more conservative and will recommend fewer articles that are more likely to be relevant to the question. However, this means there will also be more questions where Answer Bot does not make any recommendations at all. If the threshold knob is turned down, Answer Bot will recommend more articles, but there’s a higher chance that some of the articles will appear irrelevant to the end user.

Common misconceptions: What Answer Bot doesn’t do

There are some common misconceptions about Answer Bot, and machine learning in general, that can lead to confusion over how they work. In this section, we’ll address these misconceptions and hopefully give you a clearer understanding about what Answer Bot does – and doesn’t do – with your data.

Does Answer Bot learn based on end user feedback? Isn’t that where the machine learning comes in?

Although Answer Bot is powered by a machine learning model, this does not mean that Answer Bot is constantly learning. Answer Bot’s model does not incorporate feedback in real-time from end users or agents. Therefore, the feedback has no influence on which articles Answer Bot will recommend.

The end user feedback is captured and used in a number of ways:

• It is displayed to agents to provide additional context on what articles were viewed, marked as “not helpful,” or used to resolve a case
• It is exposed in reporting for admin to track Answer Bot’s performance
• It is evaluated by the data science team at Zendesk

If you see that Answer Bot is repeatedly recommending incorrect articles, the best thing to do is modify the title and the first 75 words of the articles to make the main concept more clear.

You can also create a “whitelist” of articles for Answer Bot by using labels so that Answer Bot’s suggestions will only draw from a sub-set of articles.

Is Answer Bot’s AI-powered search always better than a keyword search?

Overall, we’ve found that Answer Bot’s AI-powered recommendations are more accurate and relevant than a keyword search, especially when the question is asked as a full sentence (instead of one to three words).

However, there are times when a keyword search may work better. For example, when a user asks a single-word question via Web Widget, Answer Bot defaults to using a keyword search, as this is generally more accurate for single-word queries. The exception to this is languages, like Chinese, that do not have explicit word boundaries like spaces.

Can I “train” Answer Bot by asking the same question and answer over and over again, and responding with “Yes” or “No” to mark an article as relevant or irrelevant?

No. Answer Bot will consistently recommend the same articles regardless of any feedback from agents or end users. Answer Bot is specifically built so it doesn’t require any training to get started. It’s already pre-trained to understand natural language. If you test out a phrase/question and Answer Bot is making incorrect recommendations, the best thing to do is modify the title and the first 75 words of the articles to make the main concept more clear.

If I add labels to my articles, is that like adding a keyword to the article? Can this be done to boost how often an article is suggested?

Labels are a great way to create a “whitelist” of approved articles that Answer Bot can pull from. However, labels do not have an influence on the weighting that Answer Bot gives to each article.

If I can’t train Answer Bot, how can I improve Answer Bot’s performance?

The best way to improve Answer Bot’s performance is to consider the following:

• Analyze your Answer Bot Activity - Use Explore to see which articles are you best and worst-performing.
• The Structure of Existing Articles - Look at your help center articles and make sure that the content is concise and well organized. Each title should be phrased as a short sentence or a question.
• Content Cues - Use machine learning technology and Guide article usage data to help you discover opportunities and tasks that will improve the health of your knowledge base.

Answer Bot functionality is available in a number of Zendesk products and integrations. This article is a guide to all the ways you can use Answer Bot, and where to find more information on adding it to your toolbox.

Answer Bot in the Knowledge Capture app and Slack integration is included free of charge. An add-on subscription is required to use Answer Bot with the other features discussed in this article.

Answer Bot in Support emails

The most basic Answer Bot functionality is the automated email response. When an end user submits a support request via email, they receive an auto-response acknowledging their request. When Answer Bot is enabled, that email includes a list of articles from your Help Center that can help the requester solve their own issue:

If a suggested article answers their question, the end user can close their support request; if no article addresses the problem, the support request remains in the ticket queue to be answered by an agent.

Answer Bot in web forms

You can add Answer Bot to your web-based ticket forms as well. When enabled, if an end user submits a support request through your Help Center’s submission form, a pop-up modal offers them suggestions for articles that they may find useful:

As with the emailed suggestions, if any article in the modal answers the end user’s question, they can close the support request with no input from an agent; if it doesn’t, their request remains in the ticket queue.

Answer Bot in the Knowledge Capture app

If you’re on Guide Professional or Enterprise, and using the Knowledge Capture app, by default you have some internal Answer Bot functionality, without needing a separate Answer Bot subscription.

There are two features in the Knowledge Capture app that give your agents more access to Answer Bot functionality:

• Answer bot for agents. When a requester adds a comment to a ticket, Answer Bot looks for relevant articles, and suggests them within the app, allowing agents to view them. Agents can then decide to insert them into their response to the requester, or use the linked articles to help them craft their reply.
• Rapid Resolve. When an agent sends a link to an end user directly from the Knowledge Capture app (using Answer Bot for agents), end users can then self-solve their tickets directly from the article they’re viewing.

You can disable the self-solving option in the Knowledge Capture app, if needed. This prevents end users from closing their own requests based on articles offered by an agent, or by Answer Bot.

Answer Bot for Slack

The Answer Bot for Slack is a free feature enabled in the Slack for Zendesk Support integration if you are on the Guide Enterprise or Professional plan.

This feature allows Answer Bot to “listen in” on questions posed in any Slack channel configured to use the Support integration, and offer relevant article suggestions:

Users can indicate whether the offered article is useful to them by clicking the Yes or No buttons and, if more than one article is found, they can click the More suggestions button to view additional articles.

If their question is not answered by any of the articles offered, they can submit a Support ticket:

Answer Bot in the Web Widget

If you have the Web Widget installed on your Help Center or web site, your customers can engage with Answer Bot whenever they need help across your site, in a conversational way.

Escalation options to a human agent can always be made available, such as requesting a callback, live chat or leaving a message.

Answer Bot in the SDK

Answer Bot can be a part of your mobile support offering. Our mobile SDKs make it easy to integrate into any mobile app, answering customer questions in-context without them ever having to leave the app or disrupt their experience. Users can mark the articles as “solving” their issues, or indicate they still need help - and escalate their issue to a Support ticket.

Answer Bot APIs

The Answer Bot API enables businesses to extend AI-powered self-service help to any channel. Developers can build their own own self-service automation experiences wherever they’d like. When implemented correctly users can quickly and easily mark their questions as resolved / not-resolved giving you more data for reporting, and improving the Answer Bot model over time.

When a user submits a support request through a web form on your Help Center, Answer Bot can immediately suggest links to potentially relevant knowledge base articles.

Understanding the end user experience

With Answer Bot enabled on your web forms, the end user receives a list of suggested articles when they make a help request through your Help Center. As soon as they submit their request, an automated pop-up window appears on screen:

From this window, the end user can click any of the article titles, or the View full article button, to open the article in a new tab.

While viewing the full article, a modal appears allowing them to perform a number of related actions, including:

• Clicking the request number to view to their help request in a new tab.
• Clicking Yes, close my request to close the help request. If the end user clicks this button, they should not expect to receive any more communication about the request.
• Clicking No to open an optional feedback window, asking for more information about why the article didn’t help. If the end user clicks this button, the ticket will be handled as usual.

Enabling and configuring Answer Bot for web forms

Just as email allows you to continue to manage the triggers that Answer Bot uses to respond with the suggested articles via email, web forms allow you to select and configure each web form experience which will then render the Answer Bot pop up modal on all Help Centers and Brands within your account.

To enable web form functionality in Answer Bot

1. Click the Admin icon () in the sidebar, then select Business Rules > Answer Bot.

2. Click the Web form tab.

3. Toggle on Web form channel enabled.

   

   This displays an expandable list of your brands and their related webforms.

4. Use the toggles to determine which brands, and web forms, will use Answer Bot.

   

Testing Answer Bot results

You can use labels (as with email and triggers) to segment and refine the overall articles that Answer Bot uses when searching for the correct articles, for each brand and form. Read about the best practice for using labels with Answer Bot.

To configure and test Answer Bot labels

1. After enabling Answer Bot for a web form, hover over the form name to display the Configure and test link.

2. Click Configure and test to open the testing modal.

3. Enter sample subject and description text to view the possible Answer Bot results for those terms.

You can use labels to help with targeting for your Answer Bot triggers. Adding labels to your Answer Bot triggers is optional. Labels enable you to specify a limited subset of articles that you want to search within.

Without labels, Answer Bot searches all article titles and content to identify suggested articles. By adding labels in triggers, you can restrict the search to articles containing those labels.

This article covers three scenarios for using labels in triggers to better target articles with your Answer Bot triggers.

Scenario 1: Targeting customer segments

The most common scenario for when to use labels in triggers is when you have different customer segments and you want to show each segment only the relevant articles. For example, suppose you are a mobile game developer and you support both Android and iOS platforms. When you get a request from a customer who’s using Android, you want to show only Android articles.

To accomplish this, create an “Android” Answer Bot trigger with the condition based on your custom field “Platform = Android.” Then, configure Answer Bot using labels to include only articles that contain the “android” label.

Likewise, set up an additional trigger for the iOS platform and label.

Scenario 2: Reducing the “noise” in your Help Center

Your Help Center might contain a lot of articles, most of which you never want to be used as Answer Bot recommended articles.

In this case, review your articles and add a use_for_answer_bot label to ~200-300 of the best articles. This will allow Answer Bot to focus and only suggest articles that make sense.

Scenario 3: Conducting a limited trial for a specific type of inquiry

While not recommended (it’s a slippery slope), some customers have proven the value of Answer Bot by focussing it on a specific type of inquiry, such as “password reset” requests.

By creating an Answer Bot trigger that looks for specific words in the subject / description, and then using labels to restrict the articles suggested, you can limit the pilot and get some quantitative data to help support a broader rollout.

Figuring out the best way to set up Answer Bot triggers, automations, views, and tags can be confusing for a lot of users.

Basic tagging

Basic tagging is important for almost all configurations and best practices for Answer Bot. To allow us to optimise how triggers are fired, set up new triggers to take new actions, or change automations, we have to start with some basic tag manipulation:

1. Click the Admin icon () in the sidebar, then select Business Rules > Answer Bot.
2. For every trigger listed in the Answer Bot trigger section, select Edit.
3. Scroll down to the bottom of the trigger, to the Actions section and select Add Action.
4. Select Add tags from the drop-down list and then insert the tag answer_bot_fired.
5. Save the trigger.

Now all tickets Answer Bot has fired on will have the answer_bot_fired tag and we can easily create a view to see them:

1. Click the Admin icon () in the sidebar, then select Manage > Views.
2. Create a new view - call it Answer Bot Tickets
3. Set the conditions:
   • Ticket Status | Less than | Closed
   • Ticket Tags | Contains at least one of the following | answer_bot_fired

Tagging solved tickets

In this step, you’ll create a trigger that determines whether an end user has resolved their ticket based on an Answer Bot suggestion, and tags the ticket as solved by Answer Bot.

1. Click the Admin icon () in the sidebar, then select Business Rules > Triggers.
2. Create a new trigger - call it Answer Bot: Tag as solved
3. Set the following Conditions:
   • Ticket | Is | Updated
   • Requester Role | Is | (end user)
   • Current user | Is | (end user)
   • Ticket Status | Changed to | Solved
   • Ticket Channel | Is | Email
   • Ticket Tags | Contains at least one of the following | answer_bot_fired
4. Add the following Actions:
   • Select Add tags from the drop-down list and then insert the tag answer_bot_solved.
5. Save the trigger.

Now all tickets Answer Bot has solved will also have the answer_bot_solved tag, and we can easily create a view to see those as well:

1. Click the Admin icon () in the sidebar, then select Manage > Views.
2. Create a new view - call it Answer Bot Solved Tickets
3. Set the conditions:
   • Ticket Status | Greater than | On-hold (or Pending, if on-hold status is not available for your account)
   • Ticket Tags | Contains at least one of the following | answer_bot_solved

You should examine your ticketing workflows and make adjustments to the suggested trigger configuration to take into account non-standard ticketing workflows. For instance, if you have agents self-assigning and solving tickets without adding a public comment, the tag answer_bot_solved would be added, even though the ticket was not solved by Answer Bot. Adjusting the workflow, or adding conditions to the trigger to specify a ticket assignee, for example, can help avoid these conflicts.

Removing tags from reopened Answer Bot tickets

You could even take this one step further and add another trigger to remove the answer_bot_solved tag, if a ticket is reopened:

1. Click the Admin icon () in the sidebar, then select Business Rules > Triggers.
2. Create a new trigger - call it Answer Bot: Tag as Reopened
3. Set the conditions:
   • Agent replies greater than 0
   • Ticket tags: contain answer_bot_solved
4. Add the following Actions:
   • Select Add tags from the drop-down list and then insert the tag answer_bot_reopen.
   • Select Remove tags from the drop-down list and then insert the tag answer_bot_solved - this will remove that tag
5. Save the trigger.

Following up when customers self-solve

Extending on the previous steps, you can also add another action to send the requester a follow-up email to confirm that their request has been marked as solved.

1. Click the Admin icon () in the sidebar, then select Business Rules > Triggers.
2. Create the trigger in the previous step, or edit the Answer Bot: Tag as solved trigger
3. Add a new action:
   • Email > Requester
   • Enter an email subject and body
4. Save the trigger.

The final trigger should look like this:

Creating an Answer Bot trigger for follow-up tickets

In some situations, you may want to check in on a closed ticket. Closed tickets cannot be reopened, so to continue the conversation (rather than starting a new one) you need to create a follow-up ticket.

When you create a follow-up ticket, all of the closed ticket’s information, including tags, is carried over into the new ticket. That means that the answer_bot_solved tag is applied to the follow-up ticket, which prevents Answer Bot from firing on the new ticket. This is fine if you do not need Answer Bot to work on the new ticket; however, if you want to include Answer Bot suggestions in the ticket notifications, you’ll need to remove the answer_bot_solved tag.

To create a trigger removing the answer_bot_solved tag from a follow-up ticket

1. Click the Admin icon () in the sidebar, then select Business Rules > Triggers.
2. Create a new trigger - call it Answer Bot: Follow_up
3. Set the conditions:
   • Ticket is: Created
   • Channel is: Closed ticket
   • Ticket tags: contain answer_bot_solved
4. Add the following Actions:
   • Remove tags: answer_bot_solved
5. Save the trigger.

Suppressing Customer Satisfaction surveys on Answer Bot tickets

Customer Satisfaction surveys were designed primarily for when human agents have been involved in solving the ticket. Many customers choose to disable satisfaction surveys for Answer Bot tickets. This step assumes that you have tagged tickets solved by Answer Bot with the answer_bot_solved tag.

1. Click the Admin icon () in the sidebar, then select Business Rules > Automations.
2. Open the automation that’s been set up to send Satisfaction surveys, by default it’s called Request customer satisfaction rating (System Automation).
3. Add a new condition:
   • Ticket tags: contains none of the following: answer_bot_solved
4. Save the automation.

Zendesk Explore features a pre-built dashboard to help you monitor your Answer Bot activity and article effectiveness. The dashboard can help you identify if Answer Bot is solving your support requests, how quickly users are opening suggested articles, and how your individual articles are performing.

You can edit and customize the Answer Bot dashboard by cloning it (see Duplicating pre-built dashboards). If you need something more complex, you can write your own reports using a wide range of metrics and attributes. For details, see Getting started creating queries.

The information on the dashboard updates on the following schedule:

• Explore Lite: Each day at midnight in the timezone of the account.
• Explore Professional: Once every hour. The update time is randomized within the hour.

Accessing the Answer Bot dashboard

Use the following procedure to access the Answer Bot dashboard.

To access the Answer Bot dashboard

1. In the Zendesk product tray, click the Explore icon ().

2. From the list of dashboards, select the Zendesk Guide dashboard.

3. In the Guide dashboard, click the Answer Bot tab.

Knowledge Capture and Answer Bot are the Guide components that Explore currently reports. If they are not configured then the Guide dashboard won’t be displayed.

Understanding the Answer Bot dashboard reports

The Answer Bot dashboard shows information about Answer Bot activities, ticket resolutions, and activity by articles. You can filter the reports on the dashboard by Time, Answer channel, Answer brand, Article language, Ticket group, and Ticket form.

Answer Bot dashboard headline metrics

The dashboard displays the following headline metrics (KPIs):

• Suggestion rate: Displays the percentage of customer enquiries where Answer Bot offered a suggestion. The KPI also displays the number of answers, unsuccessful attempts, and attempts that Answer Bot made. Click the Improve link to get tips about how to improve the suggestion rate.
• Click-through rate: Displays the percentage of responses clicked by end users from the total responses offered by Answer Bot. The KPI also displays the number of clicks, clicked articles, and the median click time. Click the Improve link to get tips about how to improve the click-through rate.
• Resolution rate: Displays the percentage of enquiries that are resolved with no agent involvement. The KPI also displays the number of resolutions, indirect resolution answers, and the median resolution time. Click the Improve link to get tips about how to improve the resolution rate.
• Rejection rate: Displays the percentage of suggested article marked as unhelpful by end users from the total number of suggestion offered by Answer Bot. The KPI also displays the number of articles marked unhelpful. Click the Decrease link to get tips about how to improve the rejection rate.

Answer Bot dashboard reports

The dashboard displays the following reports:

• Answer Bot activity volumes by date: Shows the number of offered, clicked, and resolved bot answers and resolutions over the chosen time period.

• Answer Bot activity rates by date: The percentage of Answer Bot answers clicked, rejected, or resolved over the selected time period.

• Resolutions by month (12 month): The number of resolutions and the percentage resolution rate over a 12 month period.

• The following reports can be filtered by Suggested article language, Answer brand, or Answer channel:

• Answers by selected attribute (top 10): Displays the top ten offered answers by language, brand, or channel.

• Clicks and resolutions by selected attribute (top 10): Displays the top ten clicks and resolutions by language, brand, or channel.

• Resolutions by selected attribute (12 months): Displays the resolutions over the last 12 months sorted by language, brand, or channel.

• Answer Bot activity by article: A detailed report about Answer Bot activity for all of your Guide articles. You can restrict the range of results shown by using the Top and Bottom filters.

If you have added multiple brands, you can create one or more Help Centers, depending on your Support and Guide plans. A brand’s Help Center is completely separate from any other brand’s Help Center, if you have multiple. End users who visit the Help Center for a specific brand see tickets for only that brand.

If you’re using ticket forms, all ticket forms will be available in all of your Help Centers, if you have multiple.

Adding a Help Center for a brand

You can create one or more Help Centers for multibrand, depending on your plan types:

• Support Enterprise and Guide Lite or Professional: Five brands, one Help Center
• Support Enterprise and Guide Enterprise: Five brands, five Help Centers
• Support Enterprise with Multibrand add-on and any Guide plan: 300 brands, 300 Help Centers

To add a Help Center for a brand

1. Click the Admin icon () in the sidebar, then select Manage > Brands.
2. If you haven’t already done so, click Add brand to add your brand (see Adding multiple brands).
3. On the Brands management page, click the menu icon beside the brand you want to set up a Help Center for, then select Edit.

4. Under Help Center, click Create.

   

5. Click Create yours today.

6. Select a theme or click Skip for now.

   When finished, you’ll see confirmation that your new Help Center has been created.

To access a branded Help Center, see Viewing a Help Center for one of your brands.

Understanding user authentication with multiple Help Centers

When you have multiple Help Centers to support multiple brands, you cannot restrict users to a specific Help Center. All of your Help Centers are accessible to all of your end-users. If you are using remote authentication or SSO, each Help Center will redirect users to the same single sign-in protocol and database. This is because users belong to the account, not to a specific brand.

When users receive a welcome email, password reset email, or identity verification email, it will include a list of all of your Help Centers. This ensures that users understand that any changes to their account affect their access to these multiple Help Centers.

You must have Zendesk Support to have Zendesk Guide. The Zendesk Guide plans are available on any Zendesk Support plan.

Current Guide plans

The Zendesk Guide plans are:

• Guide Lite, a simple self-service solution, included at no extra cost with all Zendesk Support plans.
• Guide Professional, advanced knowledge features and customization options, available as a paid plan with any Zendesk Support plan.
• Guide Enterprise, strategic self-service experience, with advanced knowledge management and collaboration, customization options, and artificial intelligence features, available as a paid plan with any Zendesk Support plan.

You can view the features available by plan type on the Guide plan comparison page. The Guide documentation includes the plan availability for each feature.

About the Guide Legacy plan

Zendesk Support customers who were subscribed to the Team, Professional, or Enterprise plan (or the equivalent legacy Support plan) prior to May 2, 2017 are on the Guide Legacy plan, unless they have manually moved to another Guide plan.

Guide Legacy includes all existing Help Center functionality prior to the Guide release on May 2, 2017, plus any Guide Professional features released since that date. Some of those features include:

• Article History view
• Knowledge Capture app
• SEO XML sitemap
• Answer Bot compatibility, as an add-on feature

Guide Legacy customers remain on the Legacy plan, regardless of any changes to their Zendesk Support plan. Guide Legacy customers must upgrade to Guide Enterprise, to receive Guide Enterprise functionality.

Viewing your plan type

Only account owners can view their plan subscription information. If you do not have permission to view the plan subscription, ask your account owner for the plan name.

To view your plan name and features by plan type

• Click the Admin icon (), then select Settings > Subscription to see a summary of your current plan.

When you’re ready, you can activate your Help Center and make it live for end users. You must be a Zendesk Support administrator to enable Help Center. Guide Managers who are not Support administrators cannot enable Help Center.

Check out Phil Hansen’s Fine Tuning: Best practices for ticket deflection for tips on how to best promote self-service during your Help Center launch.

To activate Help Center

1. In Guide, click the Settings () icon in the sidebar.
2. In Guide settings, click the Activate button.
3. Click Activate again to confirm that you want to activate your Help Center.
4. Click Enable spam filter (see Using the spam filter to prevent Help Center spam).
5. Read the agreement, then click Enable spam filter again to agree to the terms.

Your Help Center is activated and is now visible to end users. If you need to disable your Help Center, see Disabling your Help Center.

If you are using the community, make sure that is also activated (see Getting started with Gather).

Be sure to check out our Help Center guide for end users and also our complete list of Guide resources.

You can set up your custom email domain to verify that Zendesk can send email on behalf of your email server.

For example, if you receive email from your customers at help@mycompany.com, and you’ve set up an automatic redirect to forward all email received there to Support, you can authorize Zendesk to send out notifications as if it originated from your own email address (for example: help@mycompany.com).

Setting up records for your domain can be confusing because it’s something most of us rarely do. Consult your system administrator, if you have one, before proceeding.

You don’t have to configure your email domain this way, but it’s recommended if you use your own custom email domain and have set up forwarding to an external email address. If you use a non-custom domain, such as addresses ending in @gmail.com or @yahoo.com, you can’t use this feature, as you won’t have access to the account DNS settings.

The advantages of this configuration

When Zendesk sends an email message using your email address (which is what happens if you’ve set up a support address with forwarding) the message identifies the sender as zendesk.com to avoid getting rejected. However, if you allow Zendesk to send email on behalf of your email domain, Zendesk stops sending messages from zendesk.com, and sends them from your domain, preserving your branding.

If you don’t complete the tasks described in this article, your customers might see something like this:

The following warning will also appear in the agent interface next to your external support addresses:

Setting up records for your domain

You will need to set up an SPF record and several CNAME records. Make sure you do both.

Setting up an SPF record

If this is the first time doing this task, keep in mind that you should also set up your CNAME records when you’re done.

The process of setting up an SPF record is different for different domain registrars. For example, here are the instructions for GoDaddy, Namecheap, 1&1, Network Solutions, and Google Domains.

Don’t forget to set up your CNAME records when you’re done.

To create or edit an SPF record to reference Zendesk

• Edit your domain’s DNS settings to add a TXT record. The steps vary depending on your domain registrar. A TXT record is required for your SPF record to be validated.

Zendesk recommends using the following SPF record:

v=spf1 include:mail.zendesk.com ?all

While we recommend using ?all because it’s the least intrusive qualifier, you can use whichever qualifier you are comfortable with.

If you’ve already set up an SPF record for another purpose, you can simply add a reference to Zendesk to it. The SPF specification requires that you only have one SPF record on your domain, if you have multiple records, it may cause issues, and cause rejections of your email.

For example, instead of having two separate records, such as v=spf1 include:\_spf.google.com ~all and v=spf1 include:mail.zendesk.com ~all you can combine them into one, like this:

v=spf1 include:\_spf.google.com include:mail.zendesk.com ~all

In the past, Zendesk suggested alternate formulations for SPF records, including include:smtp.zendesk.com and include:support.zendesk.com. These are both outdated SPF records. While they might still work, they’re not the best option. If you’re still using them, you’ll see a warning flag indicating you’ve set up an outdated record.

Setting up CNAME records

In order for Zendesk to send email on your behalf, you must add four CNAME (Canonical Name) records to your DNS server that give Zendesk domain-level email authorization.

The CNAME records redirect SPF checks to mail*.zendesk.com, which is a Zendesk server that includes an SPF record that is maintained by Zendesk. This SPF record is used for mail sent from zendesk*.customer.com. This means that Zendesk maintains SPF records for a subset of mail delivered from your domain, and ensures they are always up-to-date.

To authorize Zendesk to deliver your email using CNAME records

• Edit your domain’s DNS settings and add each of these CNAME records:

  Type	Name/Host/Domain	Value/Target/Destination	TTL
  CNAME	zendesk1	mail1.zendesk.com	3600 or use default
  CNAME	zendesk2	mail2.zendesk.com	3600 or use default
  CNAME	zendesk3	mail3.zendesk.com	3600 or use default
  CNAME	zendesk4	mail4.zendesk.com	3600 or use default

If you’re unsure about any of the above, consult with your DNS provider.

Consider making an additional update to digitally sign outbound email from Zendesk to prevent your customers’ email clients from blocking email. Digitally signing email provide that an email actually came from your organization and not someone pretending to be your organization. For instructions, see Digitally signing your email with DKIM or DMARC.

Verifying your domain

In order for Zendesk Support to send emails on your behalf, you must verify that you own the domain that you want Support to use. This is done by adding a TXT record (a domain verification record) to your DNS server that Support will check. The domain verification record is unique for each Support account and domain combination.

If you don’t add the domain verification record, Support sends emails from a Zendesk-provided email address. If you want to give your customers a white label experience, hiding all Zendesk branding, you must add this record.

To verify that a domain belongs to you

1. After you have finished setting up your CNAME records, go to Support and click the Admin icon () in the sidebar, and then navigate to Channels > Email.

2. Locate the DNS records (located outside of Zendesk) for your Support address, then click See details to see the domain verification value.

   If you are an agent with permissions to manage support addresses, you can use the Support Addresses API endpoint to find the domain verification code for your support address instead, if you prefer. Look for the domain_verification_code value.

3. Edit your domain’s DNS settings and add this TXT record:

   Type	Name/Host/Domain	Value	TTL
   TXT	zendeskverification		3600 or use default

   You can find the value next to the Domain verification TXT record check. In this example, the value is abcdef123456:

   

4. After you add the TXT record, click the Verify DNS records button to confirm that all of your records are now valid. If they are, the red error messages will be gone.

   After your domain is verified, leave the domain verification record in-place.

If you decide to change your Support subdomain or host mapping later, you don’t need to update your domain verification records.

Understanding SPF checks

Sender Policy Framework (SPF) is a domain level email authorization protocol that allows you to declare which IP addresses are allowed to send email as if it originated from your domain.

This is accomplished by adding Domain Name System (DNS), TXT, or CNAME records. Think of DNS as a publicly accessible record for the internet. These records enable you to state publicly that Zendesk is an authorized sender for your domain.

When an email client receives a message, it performs an SPF check on the sending domain to verify that the email came from who it says it did. If this check fails, or there isn’t a DNS record that says that Zendesk is a permitted sender, some receivers might consider that email spam or a phishing attempt, and flag it as untrustworthy or not display it to your customers at all.

Zendesk avoids this by sending email using our own domain when we’re not authorized to use your domain, and by using your domain only when you authorize Zendesk with a proper SPF record. Either way, email sent from Zendesk should never be marked as spam.

If you have multiple Help Centers, you can enable users to search across multiple Help Centers. You can decide which Help Centers to include in the search results. You can also decide if you want to include community content from those Help Centers.

You must have Guide Enterprise and Support Enterprise to support multiple Help Centers. You must be a Guide Manager to enable search for multiple Help Centers.

All of our themes support sidebar filters and results for multiple Help Centers on the Search Results page, introduced on September 25, 2019

To enable users to search across multiple Help Centers

1. In Guide, click the Settings icon () icon in the sidebar, then click Search settings.
2. Under Search across multiple Help Centers, click Show results from other Help Centers.

3. Click the Show community posts from selected Help Centers in search results if you’d like to include community posts from the selected Help Centers in the search results.

   Knowledge base articles are included by default and cannot be excluded.

   

4. Select the name of each Help Center you want to include in the search results.

   The name of each Help Center that’s been activated for a brand appears in the list. You might not have a corresponding Help Center for each of your brands.

5. Click Save in the Help Center Search settings page when you are finished.

The GitHub integration enables you to develop and maintain a theme collaboratively in GitHub, then preview or publish it in Guide. To set up the integration, make sure your theme is stored in GitHub, then set up the integration in Guide.

You must be a Guide Manager to set up the GitHub integration in Guide.

Preparing your theme in GitHub

You need to ensure that your theme is in GitHub before you set up the integration in Guide. If you’re new to Git and GitHub check out this tutorial. If your theme is already in GitHub, and it meets the following requirements, see Setting up the integration in Guide.

The integration has the following requirements for your GitHub repo:

• The manifest file must be at the root of the GitHub repo

  The file manifest.json should be placed at the root of your GitHub repository for Guide to be able to fetch your theme. You can still include extra files, such as tooling, which are ignored when importing to Guide.

• The GitHub repo can have only one theme

  You should only manage one theme in each repository. You can use the branch option during theme import to try out variations of your theme.

To get your theme into a GitHub repo

• If your theme is in Guide, export your theme from Guide and create a GitHub repo (if you don’t already have one) and push your theme to the GitHub repo.

• If your theme is not in Guide or GitHub, create a GitHub repo (if you don’t already have one) and push your theme to the GitHub repo.

After you’ve prepared your theme in GitHub, you are ready to set up the integration in Guide.

Setting up the integration

To set up the GitHub integration you need to make sure your theme is stored in GitHub, then fetch your theme from GitHub to Guide. This one-time fetch establishes the connection between your theme and GitHub.

After you set up the integration, you will work on the theme in GitHub, then update the theme in Guide when you’re ready. In Guide you can then preview or publish the theme live.

To set up the GitHub integration with your Guide theme

1. In GitHub, ensure that you have prepared your theme.

2. In Guide, click the Customize design icon () in the sidebar.

   The Themes page opens.

3. Click Add new theme in the upper-right corner.

4. Click Fetch from GitHub.

   

5. Enter the URL for the repo and, optionally, enter a branch name if you want to fetch from a branch other than the default branch, then click Import.
6. Log in to GitHub if prompted, then click Authorize Zendesk.

The theme thumbnail appears on the Themes page when the import is complete. If you have problems, see Troubleshooting the GitHub integration for Guide themes.

Once you’ve established the connection between your theme in Guide and GitHub, you will manage your theme in GitHub and update the theme in Guide as needed.

SSL (Secure Socket Layer) is an encryption protocol that ensures secure communications with your website. You must configure an SNI-based SSL certificate for a host-mapped domain using one of the two methods below:

• Use the free SNI-based SSL certificate from Zendesk (recommended)
• Use your own SNI-based certificate

If you don’t upload a certificate when you use a host-mapped domain, all help center traffic will be redirected to your default zendesk.com subdomain.

Using a Zendesk-provisioned SSL certificate

We recommend using the Zendesk-provisioned SNI-based SSL certificate for your host-mapped domain or domains if you’re on the Team, Professional, or Enterprise plans. This is included for free with your Zendesk plan. The SSL certificate covers all your host-mapped domains. Zendesk automatically renews the SSL certificate before it expires.

Your host mapping must be set up correctly before you start.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.
2. In the Hosted SSL section of the page, click Enable Zendesk-provisioned SSL.

3. Click Save.

   Zendesk requests a SSL certificate from Let’s Encrypt, a third-party certificate service. It can take up to an hour to complete the request. If you have any issues, contact support@zendesk.com.

   When you add, update, or delete a host-mapped domain, Zendesk removes your current certificate and replaces it with a new certificate that covers the new host-mapped routes.

Providing your own SSL certificate

If you prefer not using Zendesk-provisioned SSL, you can get and upload your own SNI-based SSL certificate as described in this section. If you use your own certificate, Zendesk will not automatically renew it when it expires.

Because of potentially long lead times, consider your SSL options early in the process of setting up your Zendesk Support.

Getting your own SSL certificate

If you already have a SNI-based certificate for your host-mapped address, skip to Uploading the certificate below.

You can purchase a SSL certificate from a certificate authority such as DigiCert or Symantec, or from resellers such as Namecheap. You need to give the certificate authority a certificate signing request file (CSR) to create the certificate. You can generate the CSR, as described below.

Make sure any SSL certificate you purchase supports Server Name Indication (SNI) technology.

IP-based SSL certificates are not supported.

If you have multiple host-mapped brands, you only need one certificate for all of them – you don’t need a SSL certificate for each brand. However, if you add a host-mapped brand, you need to replace your existing certificate with a new one. Generate the new certificate as described in the procedure below. For more information on host-mapped brands, see Generating an SSL certificate for host-mapped brands.

To get a SSL certificate

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.

2. In the Hosted SSL section of the page, click I do not have a certificate, and then Generate a request. A certificate signing request file (CSR) is created and downloaded to your computer.

   

3. Provide the CSR file to the certificate authority.

   The certificate authority generates a SSL certificate and gives it to you so that it can be installed on our servers.

   Certificate authorities charge a fee for each request so keep the following tips in mind:

   • Before you buy, make sure your certificate authority supports SHA-2 encryption. The CSR file generated uses SHA-2 encryption
   • Make sure the certificate supports Server Name Indication (SNI) technology
   • If prompted, specify “Nginx”, “Apache” or “Apache + mod_ssl” as the desired web server
   • After the certificate authority generates the certificate file, save it so you don’t have to make another request

   We strongly discourage using wildcard certificates. If your certificate is compromised anywhere on any of the services you use, the information on all your services is at risk. You also have to replace the certificate everywhere it’s used.

Once you have a SSL certificate, the next step is to upload it as described below.

Uploading the certificate

After purchasing the SSL certificate, the certificate authority will send you an email or direct you to a page where you can download the certificate. The instructions are often unclear about what files you really need or if you should prepare them before uploading them. For guidance, see Identifying and preparing your SSL certificate.

After obtaining or preparing the SSL certificate as a PEM file as described above, upload it to our servers as follows.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.

2. In the Hosted SSL section of the page, click I have a certificate, then Upload certificate.

   

3. Navigate to the PEM file and select it.
4. If you have a private key associated with the certificate, click Upload private key and enter your passphrase if any. You don’t need a key if you generated the CSR file in Zendesk Support. For more information, see Getting a key file for upload.

5. Click Save.

   The certificate will be installed on our servers.

Update the CNAME record

For either SSL option – you provide your own SSL certificate or you use Zendesk-provisioned SSL – Zendesk requires that the DNS record be a CNAME record that points to subdomain.zendesk.com. DNS “A” records are not supported.

You must configure the DNS, refer to Changing the URL of your Help Center. If there is an error in the DNS, we will remove the invalid host mapping.

Reviewing the SSL status of a certificate

You can review the SSL status (CNAME check) of your host-mapped, SSL-enabled brands in the Zendesk Support interface.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page. The SSL page displays information about your certificates:

   

   This view of the SSL page is only displayed if you have a host-mapped, SSL-enabled domain.

2. Refresh the page to run the SSL status check again.

Replacing a certificate

You can replace a certificate installed on Zendesk Support.

Zendesk will notify you when the certificate you provided is about the expire. If it expires before you can replace it, Zendesk will automatically replace it with a free, SNI-based SSL certificate from Let’s Encrypt, a third-party certificate service. See Getting a Zendesk-provisioned SSL certificate. You can keep the certificate or replace it with your own.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.

2. Click I already have a certificate and follow the steps in Uploading the certificate above.

   

   This view of the SSL page is only displayed if you have a host-mapped, SSL-enabled domain.

3. If you don’t have a replacement certificate yet, click I do not have a certificate and follow the steps in Getting a SSL certificate above.

Extending HTTP Strict Transport Security (HSTS) to one year

HTTP Strict Transport Security (HSTS) is enabled by default for host-mapped, SSL-enabled domains in Zendesk Support. HSTS instructs users’ browsers to access your host-mapped domain only over SSL.

When a user types http://shop.example.com or just shop.example.com to access a SSL-enabled site that doesn’t have HSTS, the user’s browser briefly accesses the non-encrypted version of the site before being redirected to the encrypted HTTPS version. The redirect makes the user vulnerable to a man-in-the-middle attack, where a hacker exploits the redirect to redirect the user to a malicious site.

When HSTS is enabled, the site instructs the user’s browser to never load the site using HTTP. The browser automatically converts all such attempts to HTTPS requests, skipping the redirect that hackers can exploit for man-in-the-middle attacks. As long as the user accessed the site once using HTTPS, the user’s browser will know to only use HTTPS to access it.

The browser remembers the site only for a specified period. By default for Zendesk SSL-enabled domains, the period is 1 day. You can increase the period to 1 year.

This feature is only available if you have a host-mapped, SSL-enabled domain.

To extend the period the browser remembers your site to one year

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.
2. Select the HSTS option to instruct browsers to remember the site for up to one year.
3. Click Save.

After setting up a host-mapped, SSL-enabled domain, you can perform any of the following management tasks:

• Reviewing the SSL status of a certificate
• Replacing a certificate
• Extending HTTP Strict Transport Security (HSTS) to one year

You can use Google Analytics to track Help Center traffic. Enabling it involves getting the tracking ID from Google Analytics and then adding it to the Help Center.

If you previously obtained the JavaScript snippet from Google Analytics and added it to your Help Center pages manually, you should remove the snippet before enabling the setting described in this article.

Adding your Help Center to Google Analytics

To track traffic via Google Analytics, you’ll need a Google Analytics account.

To create a new Google Analytics account

1. Go to www.google.com/analytics and create an account.
2. On the New Account page, click Website.

3. Use your Help Center information to fill out the account options. For example, if you’re creating an account for your company, Mondocam, you’d enter the following:

   • Account Name: Mondocam
   • Website Name: Mondocam Help Center
   • Website URL: (Select https:// from the drop-down menu) mondocam.zendesk.com/hc

   Set the remaining options according to your preferences.

4. Click Get Tracking ID and accept the Terms and Conditions.
5. Copy and add the tracking ID to the Help Center as described in Adding the tracking ID to the Help Center, below.

Once you have a Google Analytics account, you can add your Help Center.

To add your Help Center to your Google Analytics account

1. Sign in to your Google Analytics account.

2. If this is the first website associated with this Google Analytics account, click Sign Up.

   If you have other websites associated with this Google Analytics account, click Admin at the top of the page, and in the Account column, click the existing account name and select Create new account.

3. Use your Help Center information to fill out the account options. For example, if you’re creating an account for your company, Mondocam, you’d enter the following:

   • Account Name: My Company
   • Website Name: My Company Help Center
   • Website URL: (Select https:// from the drop-down menu) mycompany.zendesk.com/hc

   Set the remaining options according to your preferences.

4. Click Get Tracking ID and accept the Terms and Conditions.
5. Copy and add the tracking ID to the Help Center as described below.

Adding the tracking ID to the Help Center

Once you have your Help Center added to your Google Analytics account, you need to update your settings with the tracking ID you generated in the previous section.

To add the tracking ID to the Help Center

1. In Guide, click the Settings () icon in the sidebar.

2. Under Integrations, select the option to enable the Google Analytics and enter your tracking ID.

   

3. Click Update on the upper-right side of the page.

Using Google Analytics with Help Center

See the following resources on using Google Analytics to create the best self-service experience possible for your customers:

• Google Analytics and Help Center - Part 1: Asking the right questions
• Google Analytics and Help Center - Part 2: Measuring the effectiveness of search
• Google Analytics and Help Center - Part 3: Tracking customers’ actions
• Google Analytics and Help Center - Part 4: Fine-tuning Help Center
• Google Analytics and Help Center - Part 5: Capturing Help Center user data

An API, or Application Programming Interface, is a tool for software applications that acts as an intermediary and allows them to talk to one another. Each time you use an app like Zendesk, send an instant message, or check the weather on your phone, you’re using an API.

An example of this in the API would be the List Users endpoint. It returns a list of all users in your Zendesk Support account. Some endpoints like the Show User endpoint are more focused and just return a single thing. You can also use the API to make changes to things in Zendesk.

The API is a powerful resource that many of our customers use to bulk-import resources, create apps, pull data to external sources, and more.

Most of the reference documentation for the Zendesk API is available in the Rest API section of the Zendesk Developer Portal, which describes all the available endpoints.

Why use the API?

You can use the API to add functionality that’s not available in the UI (either natively or at your plan level) at a much faster pace than attempting to do it all by hand.

For accounts currently on the Essential or Team plans, using the API allows you to have a direct method for exporting your data without needing to upgrade to Professional (which allows for automated data exports). Similarly, you may use the API to get ticket data for reporting purposes. The API can return all information related to a ticket, so you may use the API output to pass data into a third party reporting application.

The ability to quickly update many records is another benefit of using the API. For example, while you’re only able to create a single organization at a time in the agent interface, you could create up to 100 organizations at a time with the API. In the same vein, the restrictions on how many items you can update at a time is higher with the API. The interface allows for 60 tickets to be edited at once, while the API allows up to 100 tickets.

Other common tasks include:

• Creating tickets
• Migrating ticket data into Zendesk from another system
• Editing users in bulk
• Searching records
• And many more!

Now that we’ve outlined why you’d want to use the API, let’s look at how to make an API request.

Format

The Zendesk API returns data in a lightweight format called JSON, whichlooks like this:

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
    ...
  ]
}

A typical endpoint looks like this:

subdomain.zendesk.com/api/v2/users/me.json

Endpoints can perform the following actions:

• GET - Retrieve items
• POST - Create items that didn’t exist before
• PUT - Update existing items
• DELETE - Remove items

In a browser, you can only make GET requests. You can perform the other actions using tools like cURL or the API console on the Zendesk Developer Portal.

cURL

The reference documentation uses cURL in all the endpoint examples. cURL is a command-line tool that lets you try API commands without a browser. For more information, see Installing and Using cURL in the Zendesk Help Center. You can use cURL for any of the 4 types of calls. It comes pre-installed on a Mac, but you’ll need to install it in Windows. For instructions, see Installing cURL in the Zendesk Help Center.

Status of your requests

For every API request you make, you receive a response that lets you know if it worked or not. If not, the response will provide clues as to why the request didn’t work. These responses are called status codes. Some of the most common ones are as follows:

• 200 - The request was successful
• 400 - Request was unsuccessful
• 409 - Merge or constraint error, try the call again
• 422 - Un-processible Entity
• 429 - Rate limit has been exceeded
• 500 - Warning or temporary state, contact support if it persists

See Response Codes in the API docs for more details about the status codes.

Regardless of which channel your customers use to contact you, all support requests become Zendesk Support tickets. Tickets keep track of the conversations between your customers and your agents until the issue is solved.

This article provides a guide for identifying and resolving the most frequently encountered issues when creating or updating a ticket.

1. Learn how to send an email

   In Zendesk Support, the send button is the Submit as button. You can find this button at the bottom right-hand corner of your ticket. When you click the button, select the status applied to the ticket upon submission.

   By selecting a ticket status, the ticket is updated and your message is sent provided you have the right triggers in place.

2. Find out why a ticket is marked as Open

   The New status indicates that no action was taken on a ticket. Once a ticket’s status changes from New, it can never be set back to New. Find below the situations in which the status of a ticket can change to Open.

   • An agent manually changed the status of the ticket to Open.
   • A ticket was assigned to an agent. When a New ticket is assigned to an agent, the ticket status automatically changes to Open.
   • If your account only has one agent, all tickets are automatically assigned to that agent and the status of the ticket changes to Open.
   • When a ticket is assigned to a group with one member, that agent becomes the ticket’s assignee and the status of the ticket changes to Open.
   • When an end user replies to a Pending, Solved, or On-hold ticket, the ticket status changes to Open.
   • A business rule changed the status of the ticket to Open. To find out if a business rule acts on the group of the ticket, see Viewing all events of a ticket.

3. Learn the reason why statuses change

   The status of a ticket can change for multiple reasons. Besides the reasons described in the previous point, there are other possible causes for a change in ticket status.

   • An agent manually changed the status of the ticket.
   • A business rule changed the status of the ticket. To find out if a business rule acts on the group of the ticket, see Viewing all events of a ticket.
   • Tickets are automatically closed 28 days after they’re set to Solved, regardless of any triggers or automations.

4. Understand if a message should update or create a ticket

   When a new email is received, Zendesk checks the message to determine if the email should be added as an update to an existing ticket, or if it should create a new one. The process is as follows:

   1. User sends a message to Support.
   2. Zendesk searches for the email’s Message-ID.
      • If the Message-ID matches the Message-ID associated with an existing ticket, the email threads to that parent ticket.
      • If the Message-ID doesn’t match any Message-ID associated with an existing ticket, the email creates a new ticket.

   View the original email to confirm if the email Message-IDs match up.

   If the customer replies to a ticket on the Closed status, their reply creates a follow-up ticket.

5. Track ticket changes coming from different channels and users

   You can see all the updates and notifications that happened on a ticket if you check the ticket events. Whenever you are unsure why a property of your ticket changed, check the events of that same ticket.

   The events of the ticket can also be used to troubleshoot business rules.

6. Understand if you can edit system ticket fields

   The default ticket status field is not customizable. However, you can create a custom ticket field to track any custom status you want to include in your workflow. For more information, see Can I add custom ticket statuses?.

   The priority ticket field and its values can not be edited or modified either, but you can follow Can I edit the priority field? for a workaround.

This article provides a step-by-step guide to identifying and resolving the most frequently encountered email issues.

1. Check your business rules

   Triggers and Automations, or business rules, are the features that control email notifications in Zendesk Support. A trigger that is not set up correctly can lead to an email notification at the wrong time, or not sent at all.

   Steps to resolve

   First, confirm that the default triggers that send email notifications are active in your account. Then, confirm that the conditions and actions in those triggers are configured appropriately. Finally, check the events on an example ticket to make sure an email was sent to the right user. If events indicate that happened, and they still did not receive the message, they may be suspended or rejected by your end user’s inbox.

   Here is a video tutorial to help you go through the steps to resolve:

2. What to do if “this address is already used by…“

   When adding a new support address, you may encounter an error message that says “This address is already used by {user}.”

   Steps to resolve

   An email address cannot be used both as a support address and as an identity for an agent or end user. To use the email address as a support address, you must detach it from the user it is currently associated with.

   First, find the user that currently has this email address associated with it. Then, update or remove the user to free up the email address.

   Once you have updated or removed the user, you can return to Admin > Channels > Email to add the support address. See What does the error “This email address is already used by…” mean? for detailed troubleshooting steps.

3. SPF, DNS, CNAME and TXT set up

   You may want to add your company’s email address to Zendesk so you can receive and handle tickets sent to that address. Once you’ve added the address to Zendesk, you may find that the configuration steps outside of Zendesk, with your domain provider, can get a little complicated.

   We recommend having your system or network administrator configure settings in your domain provider, but this quick video tutorial shows you or them how to configure the records provided by Zendesk.

   Gmail address

   You may encounter an error that says “Please make sure you’ve updated your Gmail settings by following the steps above.” when adding a Gmail address. This error occurs when the Gmail address is a Google Group, alias, or distribution list. See Unable to add Gmail address as an external support address for detailed troubleshooting for this error.

4. Understanding and taking action

   Ticket suspension mechanisms in Zendesk protect your account from unwanted or malicious contacts that get in the way of your day-to-day work. It’s possible for you to spot a suspended ticket that you don’t want to be suspended, though.

   Understand the cause of suspension

   When this happens, first, check the suspended queue and find the suspended ticket in question. You’ll see a cause for ticket suspension listed.

   Once you know the cause for suspension, you can take action to prevent this type of ticket from being suspended in the future. See Understanding and managing suspended tickets and spam for more detailed information.

   Viewing, recovering, deleting

   You have the option to either recover or delete the suspended ticket in question. Viewing, recovering, and deleting suspended tickets explains how to do both.

5. Avoid and control spam

   Receiving spam can be daunting. Below are steps for resolving and deleting spam tickets, as well as advice for preventing future spam.

   Steps to resolve

   First, determine how the spam tickets were created by looking at the ticket events. Once you know the channel spam is coming from, you can take specific measures to stop it. See I was hit by a spam attack. What do I do now? for detailed troubleshooting steps.

   Bulk delete spam

   Once you’ve been hit with spam tickets, learn how to clean them up in How can I bulk delete spam tickets in Zendesk? so you can get back to legitimate tickets.

   Preventing future spam

   We recommend taking some precautions to prevent spam from happening in the first place. See Tips to combat spam and protect your business for more information.