A quickstart guide to building Zendesk apps

Zendesk has a lot of documentation, and trawling through it just to get started can be taxing – so here are some tips to get you building apps fast.

App scaffold or demo apps

Zendesk supplies an application scaffold, which gives you some structure and compilation steps (think webpack, handlebars, sass) – it requires Node and Ruby.

Unless you're doing something particularly fancy, I would say you're better off starting with the demo apps. You don't need the scaffold, or handlebars, or webpack to build a Zendesk app, it's all optional, and static files are fine to start with (and maybe even forever).

You'll note that there are both v1 and v2 examples, you want v2, I will get to that.

I wanted to build a ticket sidebar app so I started playing with basic_ticket_sample_app – which adds a widget into the ticket sidebar that detects changes to the ticket and renders a sentence about them.

You can zip any one of these demo apps up, sign up for the Zendesk trial, and head to:

Settings > Apps > Manage > Private apps > Upload private app  

After you've uploaded and installed the app into your account you should see your new widget on the sidebar on existing tickets (or wherever the app you installed is meant to appear). As I am sure you've figured out by now, you can tinker with the JavaScript any make it do other more interesting things, and even build a proof of concept of your idea.

If you're tired of uploading via the interface, don't worry, there's a faster way, I'll get onto that.

Zendesk Apps Framework

Zendesk Apps Framework is a JavaScript library, you include it in your page and so long as you're code is running within the Zendesk environment you can grab data about the current context e.g. the currentUser and ticket.

Zendesk Apps Framework is the JavaScript API used to build apps and communicate with the Zendesk Support UI

They have two versions of this, v1 and v2, v1 is EOL:

Beginning August 1st, 2017, Zendesk will no longer accept Marketplace submissions for new apps created using the v1 version of the Zendesk Apps framework

And as of next year you'll need to upgrade if you want to update your v1 app:

On March 1st, 2018, no further v1 updates will be accepted to apps in the public Marketplace

In short, you want v2, and can ignore anything you read about v1.

New in v2: Iframes

The main change in v2 is that apps always run in an iframe now.

If you're replicating functionality from a v1 app, just be aware that some things v1 can do might not be possible in v2.

An example of this is that v1 sidebar apps didn't need to do any resizing, because they're part of the page flow - currently sidebar apps in v2 must either live with the default size or resize with JavaScript on load - which looks kind of janky.

I am hoping Zendesk adds a way to define dimensions in the manifest at some point 🤞️

Secure requests

Zendesk provides a proxy service for your AJAX requests so that you can AJAX things outside of the *.zendesk.com domain without dealing with CORS or the likes of JSONP.

Another benefit of the proxying service is that Zendesk allows you to swap out secure parameters within the request - very useful if you need to insert your API key but don't want end-users to see it.

If you define a secure parameter in your manifest users will be asked to supply it when they install your app:

"parameters": [
  {
    "name": "api_key",
    "secure": true
  }
]

And then you can make requests like this:

example.com/posts?api_key={{ setting.api_key }}

or like this:

Authorization: {{ setting.api_key }}

Any request like this will have the parameter swapped out in the Zendesk proxy before they hit your API, and the user is none the wiser.

Note: If you want to supply a fixed value rather than ask the agent for it, you can define your parameter with "type": "hidden" and "default": "something". I didn't find this recommended anywhere, but it seems to work, and was sufficiently secure for my needs - YMMV.

Storing "hidden" data against tickets

Zendesk supports storing data against a ticket via ticket fields – but the tl;dr is that it kind of sucks, and I stopped doing it.

The way you can do this is to specify a ticket field as a requirement:

# requirements.json
{
  "ticket_fields": {
    "my_field": {
      "title": "my field"
    }
  }
}

You can then fetch that requirement in your JavaScript, and within that the requirement_id will be your ticket field's ID in the current installation of your app (different per install):

zendesk.get('requirement:my_field').then(function(data) {  
  var tfId = data['requirement:my_field'].requirement_id
});

Once you've got the ticket field ID, you can hide the field in the UI:

zendesk.invoke('ticketFields:custom_field_' + tfId + '.hide');  

Store a string in the field:

client.request({  
  url: '/api/v2/tickets/' + tfId + '.json',
  type: 'PUT',
  data: {
    ticket: {
      custom_fields: {
        [tfId]: JSON.stringify({some: 'stuff'}),
      },
    }
  },
  dataType: 'json'
});

Fetch your string from the field:

zendesk.get('ticket.customField:custom_field_' + tfId).then(function(data) {  
  console.log(JSON.parse(data['ticket.customField:custom_field_' + tfId]));
});

There are some caveats though

  • Ticket fields can only be hidden with JavaScript.. every single time your app loads. So yeah, you can hide them, you can see me doing it above with invoke - but the user gets a flash of ticket field before your JavaScript executes, it's janky, and sucks.

  • You'll need to create a new_ticket_sidebar template even if you don't want to do anything there – just to hide the field with invoke.

  • Any update to the ticket field causes a "The ticket has been updated" box to appear for the user – so even when you hide the field, if you change anything, the user gets a message to dismiss.

In my opinion the UX problems caused by storing data in ticket fields make them unusable for storing "hidden" data.

I am hoping Zendesk allows ticket fields to be defined explicitly as hidden in advance via requirements.json at some point 🤞️

Test and package your app

You can test your app quite simply by uploading the zip file as a private app in your Zendesk account – there's a 30 day free trial if you don't have an account.

If you're fed up of clicking those buttons there's a gem for that:

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.

https://developer.zendesk.com/apps/docs/apps-v2/getting_started#zendesk-app-tools

To test your changes on Zendesk run zat create or zat update to push the app up to your Zendesk account as a private app (shortcut for uploading zip manually).

To package the app for release run zat package and the latest build will be added to ./tmp.

Summary

Zendesk apps are pretty simple, and the APIs and tooling are good – you just need to know where to look and what is useful for your project.

  • Secure requests might remove the need for you to have a server backend for your Zendesk app – you can hide keys in Zendesk and use your API directly with client-side JavaScript (via the Zendesk proxy)

  • Ticket fields are bullshit unless you want them visible to end-user – and some of the above isn't even documented anywhere I could find it

  • The demo apps and ZAT are the easiest way to whip up a proof of concept fast

I am taking on new long-term projects this month – if you need any Python, Ruby or PHP development, technical direction or product leadership – hit me up via email or grab me on Twitter.

Any Zendesk questions feel free to drop them in the comments below.

😀️✌️