Introduction to Zendesk Apps

Zendesk has announced the sunsetting of this version of the Zendesk Apps framework (ZAF v1). For more information, see https://support.zendesk.com/hc/en-us/articles/115004453028. To get started with the newer version of the framework, see the App Framework v2 docs.

Developing your own Zendesk app isn't as challenging as it might seem. First, we'll explain what apps are and then we'll take a first look at how they work. If you can't wait to start coding, see Getting Started.

What's a Zendesk app?

A Zendesk app lets you add a small amount of functionality to Zendesk Support. Examples:

  • While viewing a ticket, I want to fetch information about the customer from my back-end system and display what the customer ordered from my store, right inside a ticket
  • I want to update details about the customer from a ticket and use AJAX to send the changes to my back-end system
  • I want to track time with FreshBooks or Harvest

An app in development consists of only a few files:

app files

Files Description
app.js The nerve center of the app. This is where you define how the app reacts to different events
templates/*.hdbs Handlebars template files. Used to build the app's user interface
app.css Stylesheet for the templates
assets/*.png Images for the app
translations/*.json Translated strings to deploy the app in different languages
manifest.json Information about the app, including its author and location in the Zendesk Support interface

Here are some terms you'll see often in the docs:

Term Meaning
framework The JavaScript API used to build apps and communicate with the Zendesk Support UI
manifest A file in the app folder that lists information about the app, such as the author and locale. See Manifest
location The physical location of the app in the Zendesk Support interface. See Locations
event A way of making parts of your code run when certain things happen in Zendesk Support. See Events

First look

Here's a quick look at a simple app to help you get the lay of the land. The source code is available on Github.

Let's start with the app.js file where you define how the app reacts to different events. The framework provides a streamlined way to listen for and handle events.

// app.js file
(function() {

  return {

    events: {
      'app.created': 'sayHello'
    },

    sayHello: function() {
      var currentUser = this.currentUser().name();
      this.switchTo('hello', {username: currentUser});
    }

  };
}());

This app listens for the framework event, app.created. When detected, it runs the custom function sayHello. The sayHello function starts by getting the name of the current user from the framework's Data API. Next, it calls the framework function switchTo() to display a view in the user interface:

  this.switchTo('hello', {username: currentUser});
  ...

The first argument specifies the template to render, hello, which references the hello.hdbs file in the templates folder. The second argument specifies the data to pass to the template, expressed as a JavaScript object literal, {username: currentUser}. The current user's name is passed to the template to be displayed in the user interface.

Here's the hello.hdbs template in its entirety:

<div class="hellotext">
  <h2><strong>Hello {{username}}</strong></h2>
</div>

The Handlebars expression {{username}} inserts the value of the 'username' property of the object passed to the template. For example, if the template receives {username: 'John Smith'}, the expression inserts 'John Smith'.