Renaming your subdomain

It's important to remember that if you decide to rename your subdomain (mycompany.zendesk.com), you are actually changing the address of your account. This change is immediate. Your Zendesk account will no longer be at your old URL, and unfortunately, Zendesk cannot set up a redirect on your behalf. 

For Team, Professional, and Enterprise, host mapping (purchasing another domain that points to your Zendesk) is highly recommended as an alternative to changing your subdomain. This enables you to change the URL that your customers see when accessing your Help Center, without having to change the actual address of your agent interface or Zendesk account. To set up host mapping, see Changing the URL of your Help Center.

The tasks in this article will help alleviate the obvious concerns with renaming your subdomain, but there is always the possibility of surprise errors. Consider your entire workflow before making this change.

This article covers the following updates you will need to make:

• Step 1: Tasks before renaming your subdomain
• Step 2: Rename your subdomain
• Step 3: Tasks after renaming your subdomain

Step 1: Tasks before renaming your subdomain

Before renaming your subdomain you should update the following items:

• CNAME, host maps, and SSL
• JIRA integration

CNAME, host maps, and SSL

First and foremost, if applicable, you'll want to update any email forwarding and host mapping to point to your new support address and URL in sync with renaming your subdomain to avoid missing any incoming tickets. This includes the wildcard email option (see Accepting wildcard email addresses for support requests). You should "flip the switch" during a slow period to be sure you have time to get everything in order.

You'll also want to ensure that any CNAME changes and certificate updates are done with your customer service team in advance to changing your subdomain. You will need to add a new CNAME for your new Zendesk subdomain with a new hostmap URL. Additionally, you'll need to set up a redirect from your old hostmap to your new one. This can take time to set up. 

You can obtain a new SSL certificate by grabbing a Certificate Signing Request, and then uploading the new certificate to Zendesk Support. You need to install a new SSL certificate that covers the changed host mapped URL. For more information, see Replacing your current SSL certificate. 

JIRA

If you've enabled the JIRA On Demand integration, you'll want to update your JIRA before changing your subdomain.

To update JIRA with a new subdomain

1. Uninstall the App from Zendesk Support in the Admin >Apps>Manage Apps.
2. Disable JIRA > Admin > Manage Add-Ons > Zendesk Support for JIRA > Disable**
3. Rename your subdomain.
4. Enable the connector again in JIRA.
5. Select the Configure option in the connector setup.
6. On the next screen, click on Complete set-up to install the App.
7. Follow the on-screen instructions.
8. Go back to Zendesk Support and check to see if the JIRA OnDemand App loads properly.

Your linked tickets/issues with Zendesk Support and JIRA will not be lost in this process; we're just re-authorizing the Zendesk app.

You might have to update your other apps as well if you used OAuth credentials tied to your old subdomain.

Step 2: Rename your subdomain

When you're ready to rename your subdomain, you can follow these steps to change. Only the account owner can rename the subdomain.

To rename the subdomain

1. Click the Admin icon (  ), then select Settings > Account.
2. On the Account page, click the Branding tab.
3. Click Change your subdomain.
   
   
   Note: If you have multiple brands, click Brands menu instead of Change your subdomain.
4. Enter your new subdomain into the dialog box as shown below, and then confirm your changes by clicking the Rename Subdomain button.
   You'll need to refresh your browser to view the change.
   

The good news is not everything changes when you update your subdomain. All your existing users, tickets, organizations, and groups will automatically exist at your new URL. Additionally, your triggers and automations will be all set. While your users will need to re-login to your new Zendesk location, their profiles and ticket histories will still be intact.

Be sure to complete the tasks in the next section after you change your subdomain.

Step 3: Tasks after renaming your subdomain

After renaming your subdomain you should update the following items:

• Ticket sharing agreements
• CSAT representation/ Web Widget
• Ticket replies
• Mobile SDK
• Zendesk Talk
• API tokens/credentials
• Single sign-on
• Zendesk Chat

Ticket sharing agreements

If you have any active ticket sharing agreements, you'll need to deactivate and recreate them after changing your subdomain. This includes any receiving ticket sharing agreements, which means that you'll also need the admins of those Zendesk accounts to recreate your sharing agreements to update the location of your Zendesk account.

Sharing on individual tickets will also no longer work. After you rename your subdomain and update your sharing agreements, you'll have to manually update all shared tickets to reflect the new sharing agreement.

CSAT representation/ Web Widget

If you have any widgets, you will need to update them after changing your subdomain. You will also need to update your jQuery if you have made modifications to your CSAT representation. For more information on updating your satisfaction ratings in JSON format see, Displaying your last 100 satisfaction ratings.

You must update your widgets for your Help Center and website individually after you have changed your subdomain name.

To update your Web Widget:

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. To edit your widget on your website, go to the web page where you want to add the widget, then paste the updated code before closing HTML </HEAD> tag. You need to add the code to every webpage where you want to update the widget.

To update your Help Center widget:

1. In Help Center, click Customize design in the tools panel, then click edit them.
2. Select the Header template from the drop-down.
3. Delete any existing Help Center widget code you have.
4. Paste the updated code before the </HEADER> ; tag.
5. Click save, then click Publish changes.

For more information on updating your widgets see, Using Web Widget to embed customer service in your website.

Ticket replies

If you use email notifications, customer replies to Open or Pending ticket notifications sent prior to the subdomain change will not be received in your account or added as updates to those tickets. All ticket URLs sent in email notifications prior to the subdomain change will now also be invalid. To correct this, you'll want to update all of these with a public comment after changing your subdomain.

Start by creating a view of all the unsolved tickets in your instance of Zendesk Support. If you haven't done too much customization, you might already have this native view active in your account.

From this view, you can mass edit all your tickets with whatever comment you like. The new reply to email address will now be valid, and if you use the {{ticket.URL}} placeholder, it will populate with the updated ticket URL.

Note: You will be unable to open attachments in tickets that existed prior to the subdomain rename. Send an email to [e-mail] to have this fixed.

Mobile SDK

You will need to update the code on your Mobile SDK, so it will point to the correct Zendesk URL after you've updated your subdomain.

To update your Mobile SDK:

1. Go to Admin > Channels > Mobile SDK.
2. Locate the code snippet with your subdomain in your Android and iOS code.
3. Give your developer the updated code snippets. 

Zendesk Talk

If you experience issues with Zendesk talk after changing your subdomain, please send a request to our customer service team at [e-mail].

API authentication

If you are using Zendesk API to fetch or send data in your account, make sure to update the subdomain you are pointing to so the API call doesn’t fail.

Example:

https://{OLDsubdomain}.zendesk.com/api/v2/tickets.json \ -v -u {email_address}:{password}
https://{NEWsubdomain}.zendesk.com/api/v2/tickets.json \ -v -u {email_address}:{password}

Also, if your email address or your agents' email addresses changed, you might need to update your API tokens or credentials. For more information, see Generating a new API token in our Support tech notes.

Single sign-on

Both SAML and JWT pass the SSO request to Zendesk Access Consumer URL, which references your account subdomain. You will not be able to sign in via SSO until you update the subdomain.

For information on setting up SSO, see Using SAML for single sign-on (Professional and Enterprise) and Setting up single sign-on with JWT (JSON Web Token).

Zendesk Chat

If you originally purchased Chat separately then later linked your Chat account with your Support account, your Chat account will fail to create tickets. You will need to contact our customer service team to make changes.

If you purchased Zendesk Chat and Zendesk Support together, updates occur automatically and no action is required.