Note: ZAT is in maintenance mode. For the best experience, use the Zendesk Command Line Interface (ZCLI) to develop Zendesk apps.

Developing Zendesk apps without some local testing tools is possible but not easy. For example, each time you want to test a change, you have to package and upload the app and then install and run it remotely in Zendesk Support. To get around this problem, you can use a collection of local development tools called Zendesk Apps Tools (ZAT). Among other tasks, ZAT lets you do the following:

  • Automatically create all the necessary files and folders for a new app
  • Test your app locally in a browser
  • Validate your app
  • Package your app for upload

This article explains how to install and use the tools in the command line. If you run into any problems installing or using ZAT, refer to the known issues.

Setting up your development environment for ZAT

ZAT is a Ruby gem. A gem is a self-contained package of Ruby code. You don't need to know Ruby to use ZAT, but you will need to install a compatible version of Ruby.

Important: For ZAT, we recommend using Ruby 2.6.9. Later Ruby versions may be incompatible with some ZAT commands.

To start, you'll set up your developer environment and install rbenv. rbenv lets you install and manage different Ruby versions on your computer. rbenv makes it easier to use a Ruby version that's compatible with ZAT.

The steps to set up your developer environment and install rbenv vary based on your computer's operating system (OS):

If you use Linux, install rbenv and its dependencies using your preferred package manager. Then skip to Installing Ruby.

Disclaimer: Zendesk doesn't provide support for third-party technologies, such as macOS, Windows, or Linux.

Setting up a macOS development environment for ZAT

macOS requires a C compiler to install ZAT. You can install this compiler as part of the Command Line Tools for Xcode.

You can then use Homebrew to install rbenv. Homebrew is a command-line tool that helps you install other applications.

To set up a macOS development environment for ZAT

  1. Open the Terminal app. At the prompt, type:

    xcode-select --install

    Press Enter to run the command.

  2. When prompted, click Install and accept the legal agreement.

  3. To confirm you've installed the tools, run:

    xcode-select --version

    The command returns your current version of the tools.

  4. Install Homebrew:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Follow the prompts to complete the installation.

  5. Add Homebrew to your shell's configuration file:

    export PATH="/opt/homebrew/bin:$PATH" >> ~/.zshrc
  6. Verify Homebrew is installed and ready for use:

    brew -v

    The command returns your current Homebrew version.

  7. Use Homebrew to install rbenv:

    brew install rbenv
  8. Update your shell's configuration file to load rbenv:

    echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
  9. Reload your shell:

    source ~/.zshrc
  10. Verify rbenv is installed and ready for use:

    rbenv -v

    The command returns your current rbenv version.

Next, install Ruby.

Setting up a Windows development environment for ZAT

The Windows installer for Ruby 2.6.9 and later has a dependency issue that prevents ZAT from running in Windows. If you use Windows 10 or 11, we recommend you use the Windows Terminal app and the Ubuntu terminal environment to install and run rbenv, Ruby, and ZAT.

To set up a Windows development environment for ZAT

  1. Download and install Windows Terminal.

  2. Install Windows Subsystem for Linux (WSL) and the Ubuntu terminal environment. Follow the Install Ubuntu on WSL2 tutorial on Ubuntu.com. The instructions work for Windows 10 and Windows 11.

  3. In Windows Terminal, click the drop-down arrow and select the Ubuntu environment.

    Ubuntu comes with the Advanced Packaging Tool (APT). You can use APT to install other applications.

  4. To get the latest APT package lists, type the following in your Ubuntu terminal tab:

    sudo apt update

    Press Enter to run the command. If prompted, enter the Linux password you set when installing Ubuntu.

  5. Upgrade or install the required dependencies for Ruby and ZAT:

    sudo apt install git curl autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev ruby-dev

    The command loads several packages. It may take a while.

  6. Install rbenv:

    curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
  7. Update your shell's configuration file to load rbenv:

    echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrcecho 'eval "$(rbenv init -)"' >> ~/.bashrc
  8. Reload your shell:

    source ~/.bashrc
  9. Verify rbenv is installed and ready for use:

    rbenv -v

    The command returns your current rbenv version.

Next, install Ruby.

Installing Ruby

Use rbenv to install a Ruby version that's compatible with ZAT.

  1. List the Ruby versions available for installation:

    rbenv install --list
  2. Install a compatible Ruby version:

    rbenv install {version}

    Replace {version} with a version from the list. For ZAT, we recommend Ruby 2.6.9:

    rbenv install 2.6.9

    The command builds and installs the Ruby version from source. This can take a long time.

Using a specific Ruby version

You can use rbenv to set a default Ruby version for your computer. Later, you can use the same commands to switch Ruby versions.

  1. List your installed Ruby versions:

    rbenv versions

    To use a Ruby version that's not in the list, install it first.

  2. Set a default Ruby version for your computer:

    rbenv global {version}

    Replace {version} with a version from the list. For ZAT, we recommend Ruby 2.6.9:

    rbenv global 2.6.9
  3. Verify you're running the Ruby version:

    ruby -v

    The command returns the Ruby version you set.

Installing ZAT

Once you're using a compatible version of Ruby, you can install ZAT.

  1. Reload your shell.

    In macOS, run source ~/.zshrc.

    In the Ubuntu terminal environment for Windows, run source ~/.bashrc.

  2. Install rake, a build automation tool for Ruby:

    gem install rake
  3. Install Nokogiri 1.13.10:

    gem install nokogiri -v 1.13.10

    Nokogiri is a Ruby gem for working with XML and HTML. ZAT requires Nokogiri to run. However, versions of Nokogiri later than 1.13.10 aren't compatible with Ruby 2.6.9.

  4. Install ZAT:

    gem install zendesk_apps_tools
  5. Reload your shell.

    In macOS, run source ~/.zshrc.

    In the Ubuntu terminal environment for Windows, run source ~/.bashrc.

  6. Verify ZAT is installed and ready for use:

    zat -v

    The command returns your current ZAT version.

Updating ZAT

To update ZAT to the latest version, run:

gem update zendesk_apps_tools

Using ZAT

The ZAT tools let you do the following:

Creating starter files for a new app

You can automatically create basic starter files and folders for a new app.

To create the files

  1. In the command-line interface, navigate to the folder where you want the app files to be saved in a subfolder.

    Use the cd command (for change directory) to navigate to a child folder. Example:

    $ cd zendesk_app_projects

    To back up one directory, use cd followed by a space and two periods. Example:

    cd ..
  2. Run the following command:

    $ zat new

    The command creates a set of starter files to use with the Zendesk Apps framework (ZAF). To learn more, see the ZAF documentation.

    Alternatively, you can start an app with the Zendesk React app scaffold with the --scaffold option:

    $ zat new --scaffold

    See the React app scaffold readme on Github.

    Note: The React app scaffold is for advanced web developers. Zendesk can't provide support for third-party technologies used in the scaffold, nor can Zendesk debug custom scaffold configurations or code.

  3. At the prompts, enter your name and email, the app's name, the URL of the file to be iframed (if any), and a folder name for the app.

    ZAF apps are iframe apps. If you don't specify the URL to an iframe file, ZAT will create a basic HTML file that you can use in an iframe.

    The tool creates and lists the files. The window should look as follows in macOS:

Testing your app locally in a browser

You can start a local HTTP server and run your app locally. This ability is essential for testing and debugging your app. You don't have to package and upload the app to Zendesk Support first.

This feature is supported in Chrome and Firefox, but not Safari 9 or later. To test your app locally, ZAT runs a local http server and loads the app in the Zendesk Support https page. This results in mixed content. Chrome and Firefox block mixed content but provide a way to turn off the blocking. Starting with version 9, Safari also blocks mixed content but doesn't provide a way to turn off blocking.

Some features may not work locally. See ZAT server limitations.

To test your app locally

  1. In the command-line interface, navigate to the folder containing the app files.

  2. Start the local HTTP server with the following command:

    $ zat server

    If you get an error, make sure you navigate to your app's folder using the command line. You can start the server from a different folder by specifying the relative path to the files:

    $ zat server --path /tmp/test-app

    After a moment, a status message appears informing you that the server has started. Example:

    Note: The command prompt is unavailable until you shut down the server later.

  3. In your favorite browser, navigate to any ticket in Zendesk Support. The URL should look something like this:

    https://subdomain.zendesk.com/agent/tickets/321
  4. Append ?zat=true to the ticket URL, and reload the page.

    The URL should look like this:

    https://subdomain.zendesk.com/agent/tickets/321?zat=true

    Tip: Bookmark the modified URL for easy access in the future. You might also want to create a dummy ticket for app testing.

  5. If you're using the Chrome browser, the content of your app may be blocked. Click the lock icon on the left side of the address bar and select Site settings. On the Settings page, scroll to the Insecure Content section and select Allow.

    Click the lock icon in the address bar:

    Select Site Settings > Privacy and Security, then select Allow from the Insecure content menu:

    Note: Firefox doesn't block app content but Safari does and has no option to disable blocking. You must use Chrome or Firefox to work with the local zat server.

  6. Click the Reload Apps icon in the upper-right side of the Apps panel to load your local app into the panel.

    Even if the app appears in a Zendesk Support page, it's actually running locally on your machine.

    Note: If nothing happens, check for a shield icon in the Address bar. See step 5.

  7. Work iteratively to develop and test features in your app. For example, make some changes to your app's source code, save the changes, then click Reload Apps on the ticket page to test the changes.

  8. When you're done for the day, press Control+C to shut down the local server.

Packaging and installing a private Zendesk app

The ZAT server doesn't support some ZAF features. To preview an app that uses these features, use the zat create command instead. The command packages and installs the app as a private app in your Zendesk instance. Once installed, you can use ZAT to update the app and test changes.

  1. In the command-line interface, navigate to the folder containing the app files.

  2. Run:

    $ zat create

    If prompted, enter your subdomain, email, and password.

    The command:

    • Packages the app's files into a ZIP file. ZAT saves the ZIP file in a tmp folder in the app's root directory.

    • Uploads and installs the ZIP file as a private app in the Zendesk instance.

    • Creates a .zat file in the app's root directory. This file contains the app ID and other metadata. This app ID is unique within a Zendesk instance.

Updating a private Zendesk app

You can use the zat update command to update a private app. The command requires a .zat file in the app's root directory. The file must contain a valid app_id property.

If you uploaded the app manually, you must create and configure the .zat file first. Refer to Configuring updates. If you used the ZAT create command to upload the app, the configuration step is not necessary.

To update an installed app:

  1. In the command-line interface, navigate to the app's root directory. This is the folder that contains your manifest.json file.

  2. Run:

    $ zat update

    If prompted, enter your subdomain, email, and password.

    After the update is complete, refresh the apps in the user interface.

Configuring updates

To create and configure the .zat file:

  1. Get the app ID. Sign in to the Zendesk product for the app as an admin. Then open the respective page for the product in the same browser:

    • Support: https://{subdomain}.zendesk.com/api/support/apps/installations.json
    • Chat: https://{subdomain}.zendesk.com/api/chat/apps/installations.json
    • Sell: https://{subdomain}.zendesk.com/api/sell/apps/installations.json

    Replace {subdomain} with your Zendesk subdomain.

  2. Add a file named .zat to the app's root directory.

    In macOS, open the command-line interface, navigate to the app's root directory, and run the following command:

    $ touch .zat

    In Windows, create the file in NotePad with File > Save As.

  3. Add the following JSON to the .zat file:

    {  "subdomain": "your_subdomain",  "username": "your_username",  "app_id": 1234}

    Replace the property values with your own and save the file. The username value is the email address you use to sign in.

Validating your app

When you're finished developing your app, you should run validation tests to catch any problems before uploading it to Zendesk Support. The ZAT validation tool runs the same tests that are run when an app is uploaded to the Zendesk App Market.

To validate your app

  1. Run the following command in the folder containing the app files:

    $ zat validate

    If using the React app scaffold, run the command in the final build folder, which may be dist/ or the root folder depending on the folder structure. You can also specify the path to the final build folder with the -p option. Example: $ zat validate -p ./dist

  2. When prompted, enter the URL of the Zendesk Support instance where you plan to install the app. The command doesn't actually install the app. Specify http instead of https in the URL. Example: http://yoursubdomain.zendesk.com.

  3. Fix any problems reported by the tool.

Packaging a Zendesk app for manual upload

When you're ready to upload your app to your instance of Zendesk Support, use the ZAT tool to package the app for uploading.

  1. Run the following command in the folder containing the app files:

    $ zat package
  2. When prompted, enter the URL of the Zendesk Support instance where you plan to install the app. The command doesn't actually upload and install the app. Also, specify http instead of https in the URL.

    Example: http://yoursubdomain.zendesk.com.

    The ZAT tool packages the app and saves it in a tmp folder. Example:

  3. Grab the zip file (app-20130110164906.zip in the example) and upload it to Zendesk Support. For instructions, see Uploading.

  4. To clean up the tmp folder, run the following command:

    $ zat clean

ZAT server limitations

A few things don't work when running an app locally on the ZAT server:

  • secure settings - the ZAT server won't render the settings
  • requirements - the requirements aren't installed, so the framework's requirement() method won't work either

To get around these limitations, you can install the app as a private app and then use the zat update command to make updates to the installed app. Refer to Updating a private Zendesk app.

For other limitations, see also ZAT - Known issues.