Synchronize Algolia with your Help Center

Data connection visualization
  1. Create an Algolia account.
  2. Follow the Get Started guide to connect your Zendesk Help Center with your Agolia account.

Indexing

When you install our Zendesk integration, it creates what we call a connector in your Algolia account.
You can access it with the left sidebar in your dashboard or by following this link.

This connector will every day take your public Help Center articles and put them inside an Algolia index.
In most cases, this should be enough to have an up-to-date search.

However, if you’d rather have it updated right now, like when you add a lot of support articles, you can manually trigger a full reindex.
On this page, just click the “Reindex” button in the top right corner. A few minutes later, your search index will be updated.

Updating your Help Center theme

Once your data has been extracted to Algolia, you need to update your Help Center theme in order to replace the search feature by Algolia.

Document Head opening GIF
Document Head editing GIF

 

Available options

Here is a full breakdown of the available options for the JavaScript library:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/2/algoliasearch.zendesk-hc.min.css">
<script type="text/javascript" src="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/2/algoliasearch.zendesk-hc.min.js"></script>
<script type="text/javascript">
  algoliasearchZendeskHC({
    applicationId: '<YOUR APPLICATION_ID>',
    apiKey: '<YOUR SEARCH ONLY API KEY>',
    subdomain: '<YOUR ZENDESK APPLICATION NAME>',

    //
    // Optional configuration:
    //
    indexPrefix: 'zendesk_',              // or your custom <INDEX_PREFIX>
    baseUrl: '/hc/',                      // the base URL of your Help Center
    poweredBy: true,                      // show the "Search by Algolia" link (required if you're on Algolia's FREE plan)
    debug: false,                         // debug mode prevents the autocomplete to close when trying to inspect it
    color: '#158EC2',                     // main color (used for links)
    highlightColor: '#158EC2',            // highlight color to emphasize matching text
    responsive: true,                     // responsive instantsearch page
    autocomplete: {
      enabled: true,                      // is the autocomplete feature enabled?
      inputSelector: '#query',            // the DOM selector to select the search box
      hits: 5                             // the number of suggestions to display
    },
    instantsearch: {
      enabled: true,                      // is the instantsearch feature enabled?
      paginationSelector: '.pagination',  // the DOM selector for the current pagination (to hide it)
      reuseAutocomplete: false,           // do not add a search input for the instant-search page
      selector: '.search-results',        // the DOM selector for the results container
      tagsLimit: 15                       // maximum number of tags to display
    },
    instantsearchPage,                    // function to check if we're on the search page
    templates: {                          // template objects (see the templates section)
      autocomplete: {},
      instantsearch: {}
    },
    translations: {}                      // translation strings
  });
</script>

Customizing the CSS

It is definitely possible that, when you install the application, it doesn’t exactly display as you expect.
No worries, these are usually just a few conflicting rules between your design and our integration.

You might also just want to change the look & feel of the search.

Either way, just follow the following steps:

Example:

1
2
3
4
5
6
7
8
9
10
<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/CURRENT_VERSION/algoliasearch.zendesk-hc.min.css">
<style>
  .aa-dropdown-menu {
    background-color: #ccc;
  }
</style>
<script type="text/javascript" src="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/CURRENT_VERSION/algoliasearch.zendesk-hc.min.js"></script>
<script type="text/javascript">
  algoliasearchZendeskHC(/* ... */);
</script>

Note: You might have some trouble trying to customize the autocomplete menu because it automatically closes when you try to Inspect it.
Just set debug: true to avoid this behaviour.

Supporting multiple languages

Description

This library supports out of the box Help Centers with multiple languages.

  1. The results sent to the user are always limited to the ones in the currently selected locale.

  2. Some constant strings like the ones used in the sentence “12 results found in 1ms” need to be translated.
    The library already supports these locales:

    • ar: العربية / Arabic
    • ar-eg: العربية (مصر) / Arabic (Egypt)
    • bg: Български / Bulgarian
    • cs: Čeština / Czech
    • da: Dansk / Danish
    • de: Deutsch / German
    • de-at: Deutsch (Österreich) / German (Austria)
    • de-ch: Deutsch (Schweiz) / German (Switzerland)
    • el: Ελληνικά / Greek
    • en-au: English (Australia)
    • en-ca: English (Canada)
    • en-gb: English (Great Britain)
    • en-ie: English (Ireland)
    • en-us: English (United States)
    • es: Español / Spanish
    • es-es: Español (España) / Spanish (Spain)
    • es-419: Español (Latinoamérica) / Spanish (Latin America)
    • fi: Suomi / Finnish
    • fr: Français / French
    • fr-be: Français (Belgique) / French (Belgium)
    • fr-ca: Français (Canada) / French (Canada)
    • fr-ch: Français (Suisse) / French (Switzerland)
    • fr-fr: Français (France) / French (France)
    • hu: Magyar / Hungarian
    • id: Bahasa Indonesia / Indonesian
    • it: Italiano / Italian
    • ja: 日本語 / Japanese
    • ko: 한국어 / Korean
    • nl: Nederlands / Dutch
    • nl-be: Nederlands (België) / Dutch (Belgium)
    • no: Norsk / Norwegian
    • pl: Polski / Polish
    • pt: Português / Portuguese
    • pt-br: Português do Brasil / Brazilian Portuguese
    • ro: Română / Romanian
    • ru: Русский / Russian
    • sk: Slovenčina / Slovak
    • sv: Svenska / Swedish
    • th: ไทย / Thai
    • tr: Türkçe / Turkish
    • uk: Українська / Ukrainian
    • vi: Tiếng Việt / Vietnamese
    • zh-cn: 简体中文 / Simplified Chinese
    • zh-tw: 繁體中文 / Traditional Chinese

    If you want to support another locale, please help us by opening an issue on GitHub.

Modifying translations

If some translations don’t fit what you want, you can change them using this syntax:

1
2
3
4
5
6
7
translations: {
  placeholder: {
    de: 'In unseren Help Center suchen',
    'en-us': 'Search in our Help Center',
    fr: 'Recherchez dans notre Help Center'
  }
}

For reference, here is the list of all the translations for the en-us locale:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
translations: {
  categories: {
    'en-us': 'Categories'
  },
  change_query: {
    'en-us': 'Change your query'
  },
  clear_filters: {
    'en-us': 'clear your filters'
  },
  format_number: {
    'en-us': function (n) { return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ','); }
  },
  filter: {
    'en-us': 'Filter results'
  },
  nb_results: {
    'en-us': function (nb) {
      return this.format_number(nb) + ' result' + (nb > 1 ? 's' : '');
    }
  },
  no_result_for: {
    'en-us': function (query) {
      return 'No result found for ' + this.quoted(query);
    }
  },
  no_result_actions: {
    'en-us': function () {
      return this.change_query + ' or ' + this.clear_filters;
    }
  },
  placeholder: {
    'en-us': 'Search in our articles'
  },
  quoted: {
    'en-us': function (text) { return '"' + escapeHTML(text) + '"'; }
  },
  stats: {
    'en-us': function (nbHits, processing) {
      return this.nb_results(nbHits) + ' found in ' + processing + ' ms';
    }
  },
  search_by_algolia: {
    'en-us': function (algolia) { return 'Search by ' + algolia; }
  },
  tags: {
    'en-us': 'Tags'
  }
}

Localized tags

You can index localized tags based on locales prefix (e.g. en-us or en).
If we detect a locale, we’ll only index localized tags for this translation.
For instance, an article with those tags:

1
2
3
4
5
6
[
  'Wow',
  'en:Awesome',
  'en-gb:Good',
  'fr:Incroyable'
]

For fr and fr-* locales, we’ll index { "label_names": ["Incroyable"] }.
For en-au, en-ca and en-us locales, we’ll index { "label_names": ["Awesome"] }.
For the en-gb locale, we’ll index { "label_names": ["Good"] }.
For all the other locales, we’ll index { "label_names": ["Wow"] }.

We do not index community forums for now. If you’re using them, you’ll probably want to disable instantsearch by setting enabled: false and just use the auto-complete feature.

Indexing private articles

Since we’re providing a front-end search, and we can’t securely know which access a user has in Zendesk’s templates, we have to limit our indexing to public articles only.
A public article is not a draft and its access policy is everybody.
If you’re in such a scenario, we recommend you to disable instantsearch by setting enabled: false and just use the auto-complete feature.

Modifying templates

WARNING: We don’t provide any guarantee that we won’t change the templates between versions.
If you chose to modify a template, you’ll need to lock your version to MAJOR.MINOR.PATCH instead of just MAJOR in

1
2
<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/2/algoliasearch.zendesk-hc.min.css">
<script type="text/javascript" src="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/2/algoliasearch.zendesk-hc.min.js"></script>

The latest version is version.

With your version locked in place, you can now look at templates.js to know which keys you can override.
The code here is ES6, you’ll need to rewrite your custom template using Vanilla JavaScript instead.
Also, some templates are using a compile function in this file. This function is internally calling the Hogan.js template engine with square brackets instead of braces (because Zendesk templates already use braces). This function is available using algoliasearchZendeskHC.compile.