Renaming your subdomain

What's my plan?

Suite

Team, Growth, Professional, Enterprise, or Enterprise Plus

Support

Team, Professional, or Enterprise

You must be the account owner to rename a subdomain. If you aren't the account owner, you can find the account owner and request they make the change. You cannot rename the subdomain of a sandbox account.

Zendesk can't change your account's subdomain for you. If you can't find the account owner, work with your IT administrators. If you can’t resolve this, contact Zendesk Customer Support to initiate a security review.

Renaming your subdomain takes effect immediately. Your Zendesk account will no longer be at your old URL, and Zendesk cannot set up a redirect on your behalf. Consider your entire workflow before making this change.

Warning: Renaming your subdomain (mycompany.zendesk.com) actually changes the address of your account. Be sure you read and understand the Important considerations before renaming your subdomain.

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

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

Important considerations before renaming your subdomain

Before you rename your subdomain, consider simply changing your account name or setting up host mapping as alternatives instead.

Host mapping (purchasing another domain that points to your Zendesk) is highly recommended as an alternative to renaming 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. See Changing the URL of your help center.

If you want to proceed with renaming your subdomain, make sure you understand the following important considerations:

• Renaming your subdomain takes effect immediately, so it’s recommended to make the change during low-volume hours or after your business hours because some functionality is affected.
• Renaming your subdomain changes the URL of your help center (for example, myoldsubdomain.zendesk.com/hc to mynewsubdomain.zendesk.com/hc). You may need to update links or bookmarks referencing the old help center URL to ensure users can access the correct site. Additionally, you should communicate this change to your customers to avoid confusion.
• There may be a delay of several hours before you can add new native support addresses. When adding a support address, check that the new subdomain appears on the "Create a new support address" form. If the old subdomain appears, check back again in a few hours.
• Chat may be inaccessible for up to 2 hours after changing your subdomain. We highly recommend you change your subdomain after hours.
• If you have a Sell-only account or a Sell+Chat account, it's not possible to change the subdomain in Admin Center. Contact Zendesk Customer Support for help.
• If you use Sunshine Conversations through the Agent Workspace and want to change your subdomain, you must delete and then recreate your Sunshine Conversations integrations. We recommend using host-mapped domains instead of changing a subdomain. Note that changing your subdomain will halt all Zendesk bot and autoreply activity. If you want to continue your Zendesk bot activity, don't change your subdomain.
• Customers using the Authenticated SMTP Connector will need to deprecate their usage before renaming their subdomain, then re-add their configuration once the subdomain change is complete, as this feature is subdomain-specific and will not automatically update.
• Access to many early access programs (EAPs) is controlled by the account subdomain. If you change your subdomain, you will lose access to any EAPs controlled in this manner. You must sign up again for those EAPs with your new subdomain.
• Changing your subdomain will break links to inline images in tickets because these images include your subdomain or hostmap name in the URL.
• After you change your domain, you cannot copy and paste comments (internal or public) or images from a ticket created in the old domain. Doing so results in broken images and incomplete comments. You must recreate comments or re-upload the image attachments directly into the ticket in the new domain.

Step 1: Tasks before renaming your subdomain

Before renaming your subdomain, you should update the following items:

• Email forwarding from external addresses
• CNAME, host maps, and SSL
• Jira integration

Email forwarding from external addresses

You need to update any email forwarding 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.

Things to consider:

• You are responsible for migrating external addresses. Zendesk cannot migrate external addresses automatically.
• Ensure all your external addresses route to the new subdomain, and remove all routing rules for the old subdomain.
• If you forward email from multiple external addresses to multiple Zendesk addresses, you must temporarily consolidate email traffic under your default support address (support@new_subdomain.zendesk.com) or enable wildcards. Although it may take several hours before you can add new native support addresses using the new domain, the default support@new_subdomain.zendesk.com address is available right away.

CNAME, host maps, and SSL

Update any host mapping to point to your new support address and URL. Ensure that any CNAME changes and certificate updates are done with your customer service team before changing your subdomain. You must 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 must install a new SSL certificate that covers the changed host mapped URL. For more information, see Replacing a 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. In Admin Center, click Apps and integrations in the sidebar, then select Apps > Channel apps.
2. Disable the Jira app.
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

Follow these steps to rename your subdomain. You must be the account owner to rename a subdomain. If you aren't the account owner, you can find the account owner and request they make the change.

Zendesk can't change your account's subdomain for you. If you can't find the account owner, work with your IT administrators. If you can’t resolve this, contact Zendesk Customer Support to initiate a security review.

Note: When you rename your subdomain, you must choose a name that contains between 3 and 63 characters. You can't use underscores (_) or other special characters as part of the name. It can include only letters A-Z, numbers 0-9, and dashes (-).

To rename the subdomain

1. In Admin Center, click Account in the sidebar, then select Appearance > Branding.
2. In the Subdomain section, click Change your subdomain.
   

   Note: If you have multiple brands, click Brands menu instead of Change your subdomain.
3. Enter your new subdomain into the dialog box as shown below.

   

4. Confirm your changes by clicking Rename Subdomain.

   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 sign in again 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 (Classic)
• Ticket replies
• Mobile SDK
• Zendesk Talk
• API tokens/credentials
• Single sign-on
• Zendesk messaging
• Zendesk Chat
• Zendesk Workforce management (WFM)
• Status notifications
• Explore

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 (Classic)

If you are using one or more instances of Web Widget (Classic), you must 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 Web Widget (Classic):

1. In Admin Center, click Channels in the sidebar, then select Classic > Web 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 (Classic) to embed customer service in your website.

Ticket replies

If you use email notifications, customer replies to 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 cannot open attachments or view inline images in tickets that existed before the subdomain rename. Contact Zendesk Customer Support to have inline images fixed. Image links copied and pasted from other sources cannot be fixed. Attachments cannot be retrieved.

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. In Admin Center, click Channels in the sidebar, then select Classic > 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, contact Zendesk Customer Support.

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 Managing access to the Zendesk API.

Single sign-on

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

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

Zendesk messaging

When you change your subdomain, a new messaging Web Widget script is generated. You must update all pages of your site/application to use the new script. See Installing the Web Widget on a website.

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.

Zendesk Workforce management (WFM)

When you rename your Zendesk subdomain, rename your subdomain on Zendesk WFM to ensure the accounts match and your historical data and settings are intact.

Warning: Once you renamed the subdomain on the Zendesk side, and you have not updated it on Zendesk WFM yet, the app on the top right of Zendesk, a Complete installation message will display. Do not continue with the new installation, as it will create a new Zendesk WFM account.

To rename your Zendesk WFM subdomain

1. Once you have renamed your Zendesk subdomain, contact Zendesk Customer Support with your previous Zendesk subdomain and your new renamed subdomain.
2. Zendesk will update your subdomain and invite you to reauthorize the account.

Status notifications

If you subscribed to Zendesk status notifications, update your subscription with your new subdomain.

Explore

You may see some delayed (or missed) scheduled dashboard deliveries while your account re-synchronizes with Explore.