Because a Zendesk app runs in an iframe in the product, you can use a server-side web application to generate the content for the iframe. You can use any server-side technology you want so long as you have a component that can send HTML pages in response to HTTP requests.

In this 5-part tutorial series, you'll learn how to build a server-side Zendesk app. The first part covers the following core concepts about building server-side Zendesk apps:

The other tutorials in the series teach you how to build and deploy a simple server-side app:

The tutorials build on each other, so tackle them in order before moving on to the next one.

Disclaimer: Zendesk provides this article for instructional purposes only. The Zendesk Support team does not provide support for the content. Please post any issue in the comments section below or in the Zendesk Apps community, or search for a solution online.

What you'll need

To build and upload a private app, you must have Zendesk Support on the Zendesk Suite Professional plan or above. If you're on the Essential or Team plan, Zendesk offers developers a free, sponsored Enterprise account for testing and debugging apps. We ask only that you don't use it to provide actual support. See Request a sponsored test account.

You can also try out apps in the Trial account, which gives you access to all Professional features.

On the technical side, you'll need Python 3 and a pair of Python libraries. For details, see Create a web application.

Specifying the first page to display

When the app starts in a Zendesk product, the product sends a request for the first page to display in the iframe. You specify the first page's URL in the app's manifest.json file. Example:

...{  "location": {    "support": {      "ticket_sidebar": "https://omniwear.com/apps/my_app/sidebar"    }  }}

Make sure your web app serves an HTML page in response to a request to that URL.

Installing a basic framework app

Even if you're building a server-side app, you must still package the following required files in a framework app, and then upload and install the app in the Zendesk product:

  • A manifest.json file in the app's root folder - See the previous section and the Manifest reference in the reference docs
  • A translation file named {locale}.json in a folder named translations in the root folder - The value of {locale} is specified by the defaultLocale property in manifest.json. For example, if "defaultLocale" is "en", then make sure a file named en.json exists in the translations folder. See Apps internationalization in the reference docs
  • A small app icon named logo-small.png in a folder named assets in the root folder - The image is used in the header of the app. You can still upload and install the app without it, but a broken image icon will appear in the app's header. See Styles and assets in the reference docs for the image specifications
  • A larger app icon named logo.png in the assets folder - The image is used in the product admin pages for managing apps. You can still upload and install the app without it but a broken image icon will appear in the interface. Styles and assets in the reference docs for the image specifications
  • Possibly additional branding assets if you plan on making the app available in the Zendesk Marketplace (as opposed to creating a private app to run only in your Zendesk product). See Create assets in Publish your app.

Accessing framework APIs

Server-side apps access framework APIs the same way client-side apps do. First, each HTML file that needs to access the framework imports the ZAF SDK in a script tag. Example:

<script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>

Second, the page creates a ZAFClient object, and then calls methods like client.get() or client.invoke() to access the framework APIs from the iframe. Example:

var client = ZAFClient.init();client.invoke('notify', 'Ticket successfully updated!');

To learn more, see Using the Apps framework in the developer docs.

The big difference is that the web app must provide the following 2 parameters that the ZAF SDK needs to create a client object:

  • origin - the url of the host Zendesk product. Example: https://omniwear.zendesk.com
  • app_guid - the app's unique identifier. Unlike an id typically returned by an API, an app_guid value is ephemeral

The Zendesk product provides these values to a web app when it requests the first page (the page specified in the app's manifest file). It appends the values to the URL as query string parameters. For example, if your manifest specifies https://omniwear.com/apps/my_app/sidebar as the first page to display in the iframe, then the product will use the following URL to request the page:

https://omniwear.com/apps/my_app/sidebar?app_guid=f278bc69-6098-aab88a5ec49f&origin=https%3A%2F%2Fomniwear.zendesk.com

Your web app must retrieve the query string and append it to the link URL of any framework-interactive page. Example (using Bottle, a Python micro web framework):

@route('/sidebar')def index():    qs = request.query_string    return template('<a href="manage?{{qs}}">Manage tasks</a>', qs=qs)

The route grabs the query string sent by the Zendesk product, appends it to the Manage tasks link URL, then returns a simple first page consisting only of the link.

When the user clicks the Manage tasks link in the app, the query string in the URL is sent to your server and then returned to the iframe in the response's referer header, along with the requested page. The ZAF SDK can then use the origin and app_guid parameters behind the scenes to create a client object for the page:

var client = ZAFClient.init();// now do something with the client

ZAFclient.init() returns false if the query string parameters are wrong.

Now that you understand the basics of server-side Zendesk apps, you can start building your own. In the next tutorials in the series, you'll learn how to build a small server-side app that integrates with Asana, a popular task management application. Get started: Part 2 - Display server-side content in a Zendesk app.

Join the discussion about this article in the community.