Getting started

The Zendesk Apps framework (ZAF) v2 lets you add features to, or build integrations with, a Zendesk product. Because the apps run in iframes in the product, you can build apps with any technology you like, including server-side technologies. The framework also gives your apps access to various product resources using consistent APIs across supported Zendesk products.

How does it work?

All apps have a manifest.json file that specifies one or more locations in the product, such as the ticket sidebar or the nav bar. The locations are where iframes can appear in the product. You specify the page to display in the iframe at the specified location. Example:

  "location": {
    "support": {
      "ticket_sidebar":  "assets/start.html"

You can then build the app using any client-side or server-side technology you like. If you only use client-side technologies like HTML, JavaScript, and CSS, you can let Zendesk host the app. If you prefer using server-side technologies, you can host the app on a remote server.

If you want a page in your app to interact with framework APIs, import the ZAF SDK. Example:

<script src=""></script>

With the SDK in place, you can create a ZAFClient object that lets you communicate with the host Zendesk product:

var client = ZAFClient.init();
client.get('').then(function(data) {
  console.log(data); // { "": "Mikkel Svane" }

To learn more, see Working with framework APIs.


For reference documentation, see:

Zendesk App Tools

The Zendesk App Tools (ZAT) are a collection of local development tools that simplify building and deploying Zendesk apps. The tools lets you create, test, validate, and package your apps.

ZAT is a Ruby gem -- a self-contained package of Ruby code that extends Ruby. You don't need to know Ruby to use the tools but you do need to install Ruby to install the gem.

To install the tools, see Installing and using the Zendesk apps tools. See the known issues if you run into any problems installing or using the tools.

To update your tools to the latest version, run $ gem update zendesk_apps_tools.

The tools consist of the following commands.


Creates all the files necessary to start building a Zendesk app.

$ zat new

Runs a suite of validation tests against your app. Because the same tests are run when you upload the app, you probably won't be able to upload the app until your app passes the validate tests.

$ zat validate

Starts a local HTTP server that lets you run and test your apps locally.

$ zat server

Run the command in the app's local root folder. Switch to the product interface and append ?zat=true to the page URL. Finally, allow mixed content (http and https) in your browser by clicking the shield icon on the right (Chrome) or lock icon on the left (Firefox).

For details, see Testing an app locally.

You can also test apps with secure settings locally. See Testing an app with secure settings locally.

To stop the server, switch to your command-line interface and press Control+C.


Packages, uploads, and installs the app in a Zendesk Support account.

Note: Installing is supported only in ZAT v2.0 or later. Packaging and uploading is supported in all versions. Run zat -v to get your version.

The command performs the following actions:

  • Packages the app's files into a zip file and saves it in a local folder named tmp
  • After prompting you for a subdomain, username, and password, uploads and installs the package in a Zendesk Support account
  • After uploading the app, saves the app ID and other metadata in a file named .zat in the local folder


$ zat create

The command has the following options:

  • no-install - Prevents the app from installing in the product instance. The app will still be uploaded and appear in the "Not Installed Apps" section of the Private Apps tab in the admin interface. Example:

    zat create --no-install

  • path - Specifies a folder containing the app files to package and upload. Example:

    zat create --path=./dev/zendesk_app

  • zipfile - Specifies a folder containing a packaged zip file. Use this option if you used package to package the app and you want to upload and install it. Example:

    zat create --zipfile=~/my_app/tmp/


Updates an existing private app in a Zendesk Support account.

$ zat update

The command packages the app's files and uploads the package to a Zendesk Support account. It prompts you to enter a subdomain, username, and password.

The command has the following options:

  • path - Specifies a folder containing the app files to package and upload. Example:

    zat update --path=./dev/zendesk_app

  • zipfile - Specifies a folder containing a packaged zip file. Use this option if you used package to package the updated app and you want to upload and install it. Example:

    zat update --zipfile=~/my_app/tmp/

If you didn't use create to upload the app initially (for example, if you uploaded the file using the product admin interface), you must create a file named .zat with the following content in the app's local root directory:

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

Note: The create command creates this file for you.

The username value is the email address you use to sign in.

You can obtain the app_id by signing in to Zendesk Support as an admin and opening the following page in the same browser, replacing your_subdomain with your own:

For details, see Updating an installed app.


Creates a zip file that you can upload and install in a Zendesk Support account.

$ zat package

The command saves the zip file in a folder named tmp.

You can upload and install the app from the product admin interface or from the command line using the create command with the zipfile option.


Removes the zip files in the tmp folder that's created when you package the app.

$ zat clean