Zendesk app quick start

In this 15-minute quick start, you'll use the Zendesk Apps framework to access ticket data. You'll also use the framework to add a comment to a ticket as well as create a ticket.

A Zendesk app is simply a small HTML application installed in the agent interface that extends the product's functionality in some way.

To keep things simple in this quick start, you'll install and use an app named REPL in Zendesk Support. REPL is itself a Zendesk app that works just like the JavaScript console in your web browser. It lets you try out different framework code snippets without building an app.

Here's REPL in the ticket sidebar:

Note: REPL is not supported in Zendesk Chat.

Preparation

1. If you don't already have a Zendesk Support account, register to start a free trial at https://www.zendesk.com/register/.

2. In your browser, navigate to the REPL v2 app in the Zendesk Marketplace at https://www.zendesk.com/apps/support/v2-repl/.

   

3. Click Install to start the installation process, select your Zendesk Support account, then click Install:

   

4. Accept the terms and license and click Install:

   

   The app is installed in several locations in the agent interface -- the nav bar on the left, the top bar, and the sidebar of the Ticket, New Ticket, User, and Organization pages.

   

Access data

The Apps framework has lots of APIs that give apps access to all kinds of data in your Support or Chat accounts. Use the framework's get() method in your apps to retrieve the data.

Try it out

Let's get data from a ticket that's open in the agent interface.

1. Open any ticket in the agent interface.

2. Open the REPL app in the ticket sidebar. If you don't already see the app in the sidebar, click the Apps button in the upper-right side of the ticket interface.

   

   The REPL app is installed in several locations in the agent interface. However, all locations are not created equal. Some data is available in some locations but not in others. This tutorial uses code that works in apps in the ticket sidebar location but not necessarily in apps in different locations. To see what's available where, see the locations in the developer docs.

3. Enter the following statement in the text box on the lower side of the REPL app in the ticket sidebar and press Enter:

   zafClient.get('ticket.subject')
   

   Example:

   

   After hitting Enter, you should see something like the following response:

   

   The response tells you there were no errors and that the ticket subject is "My printer is on fire!".

4. Update the ticket.subject property with the set() method:

   zafClient.set('ticket.subject', 'My copier is on fire!')
   

   The statement changes to subject of the ticket to "My copier is on fire!":

   

As mentioned earlier, the data you can access depends on the location of your app in the agent interface -- nav bar, top bar, or page sidebars. For example, the ticket subject (or any ticket data) is unavailable in apps running in the nav bar:

For a full reference of the data you can access in each location, see Zendesk Support API in the Apps documentation.

Use an action

As well as accessing data, you can also use the framework to perform, or invoke, actions. For example, the ticket comment object not only has several properties, but the following actions too:

• comment.appendHtml
• comment.appendMarkdown
• comment.appendText

Use the framework's invoke() method in your apps to use actions.

Try it out

Let's add a comment to a ticket.

1. Open a ticket in your agent interface.

2. In the REPL app in the ticket sidebar, enter the following statement and press Enter:

   zafClient.invoke('ticket.comment.appendText', 'On it!')
   

   The statement inserts "On it!" in the comment editor:

   

Like data, the actions you can invoke depend on the location of your app in the agent interface -- nav bar, top bar, or page sidebars. See the API docs for details.

Make a request

If you can't find anything in the framework APIs to meet a particular need, no problem. You can use the Zendesk REST API or an external REST API. The framework lets you make HTTP requests using whatever JavaScript functions you like, including jQuery or native JavaScript methods. You can also use the framework's request() method in your apps.

The request() method not only simplifies using the Zendesk API, it eliminates the cross-domain headaches associated with making external API requests from a browser.

Tip: You can also make server-side HTTP requests with technologies like Python, Ruby, or PHP, but that's a subject for another day.

Try it out

Let's use the Zendesk REST API to create a ticket from an app. To create a ticket, you make a POST request to the /api/v2/tickets.json endpoint. You can find all the details about the Tickets API in the developer docs, but for now let's just dive in.

1. Open the REPL app in any location.

2. Paste the following statement as a single block and press Enter:

   zafClient.request({
     url: '/api/v2/tickets.json',
     type: 'POST',
     contentType: 'application/json',
     data: JSON.stringify({
       "ticket": {
         "subject": "Test ticket #1",
         "comment": { "body": "This is a test ticket" }
       }
     })
   })
   

   The framework's request() method creates a ticket in your account and returns the following information:

   

   The response lists all the properties of the new ticket. Check out the properties you set yourself (description and subject) and the ones the system set for you, such as status. Naturally, you could have set the ticket status in the request yourself, as follows (in bold):

   data: JSON.stringify({"ticket": {"subject": subject , "status": "open", "comment": { "body": body }}})

3. Switch to the agent interface to view your new ticket (click Views then Unassigned tickets):

   

To clean up after yourself, delete the test ticket by selecting it in the list, clicking the Edit Tickets button in the upper-right, and selecting Delete.

Next steps

The best way to learn to build Zendesk apps is to keep trying different framework APIs in REPL in different locations in the agent interface. Once you're comfortable with how it all works and start seeing the possibilities, build an app or two. Use any of the following resources along the way:

• Learn the basics in How does it work? in the developer documentation

• Find out more about the framework APIs and events in Working with framework APIs and Working with framework events

• Get hands-on with Building your first Zendesk Support app or Building your first Zendesk Chat app, each a five-part tutorial series that describes how to build a simple client-side app from scratch

• Try tutorials and read articles in the Apps developer guide on the Zendesk Help Center

• Peruse the Apps reference documentation on the Zendesk developer portal

• Learn about making your apps available in the Marketplace

• Ask questions or look for answers in the Zendesk Apps developer community.