Migrating our old support website to Zendesk Help Center with Temporary Redirects

When I migrated my existing support website to Zendesk Help Center, I wanted to ensure a seamless experience for my users. One challenge I faced was handling redirects for my old articles. Since Zendesk doesn’t natively support 301 (Moved Permanently) server-side redirects, I needed to find a workaround to ensure users could still access the content without requiring an intermediary server. Unfortunately, Zendesk is working on a feature supporting 301 redirects, but it’s not released yet, as of now (https://support.zendesk.com/hc/en-us/community/posts/4409222574874-Allow-Redirect-of-Urls).

In this blog post, I will share a temporary workaround I used for redirecting old articles to their new locations in Zendesk Help Center using client-side redirects.

Step 1: Prepare the Redirects JSON File

I first created a JSON file containing the mapping of the old article URLs to their corresponding new URLs in the Zendesk Help Center. The JSON file has a structure like this (make sure to replace the example URLs with the actual old and new URLs for your articles), place this file in your assets folder in your theme and name it redirects.json:

{
  "https://old-support.example.com/article1": "https://my-helpcenter.zendesk.com/hc/en-us/articles/123456789-article1",
  "https://old-support.example.com/article2": "https://my-helpcenter.zendesk.com/hc/en-us/articles/123456789-article2",
  ...
}

Step 2: Add the Redirect Script to Zendesk Help Center

Next, I added the following JavaScript code to the Zendesk Help Center theme. You can do this by editing the document_head.hbs file in the templates folder in your theme.

// This will create a direct link with your redirects file in the assets folder
<script> var assetsRedirect = "{{asset 'redirects.json'}}"; </script>

<script>

  // Replace old-support and domain in urlPattern
  var urlPattern = /^https:\/\/old-support\.domain\.com\/kb\/en/;
  var currentUrl = window.location.href;

  if (urlPattern.test(currentUrl)) {
    fetch(assetsRedirect)
      .then(function(response) {
        if (response.ok) {
          return response.json();
        } else {
          throw new Error('Failed to fetch the JSON file');
        }
      })
      .then(function(redirects) {
        var redirectTo = redirects[currentUrl];

  			if (redirectTo) {
          window.location.replace(redirectTo);
        } else {
          console.error('No matching URL found in the JSON file');
        }
      })
      .catch(function(error) {
        console.error('Error:', error);
      });
  }
// });
  
</script>

Make sure to replace old-support.domain.com with the actual domain of your old support website.

This script checks if the current URL matches the pattern of the old support website. If it does, it fetches the JSON file, finds the matching old URL, and redirects to the corresponding new URL in Zendesk Help Center.

Step 3: Test, test, and test your redirects

Finally, I tested the redirects by visiting some of the old article URLs to ensure they were correctly redirecting to the new Zendesk Help Center articles.

Keep in mind that this approach is a temporary workaround using client-side redirects, and it won’t send a 301 Moved Permanently status code. This solution is suitable if you don’t want to add an extra server as an intermediary for handling server-side redirects. However, if you can update your old support website’s server configuration, it is recommended to use server-side redirects for a more SEO-friendly solution.

Daniel Nikolic

Is interested in everything connected to technology. Has a passion for cloud, virtualization and software development. Always finds appropriate IT solutions for customers that match their needs strategically, technically and financially.

Core qualities
Quick thinker, result driven, ambitious, customer-friendly, enthusiastic

Hobbies
Running, listening to music, good food and doing fun things with family

Job description
CTO PepperByte, LoadGen, and BlueParq