Building a server-side app - Part 2: Display server-side content in a Zendesk app

In the previous tutorial in this series, you learned core concepts about server-side Zendesk apps. In this tutorial, you'll build a small web app that displays server-side content in a Zendesk app.

The tutorial covers the following tasks:

This tutorial is the second part of a series on building a server-side Zendesk app:

To keep things simple, you'll build the web application using a Python micro web framework named Bottle. You'll need only two dozen lines to build a working web app for this tutorial. The framework helps keep technical details to a minimum so you can focus on the logic, which you can apply in another framework if you want.

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 Zendesk Apps framework (ZAF) community, or search for a solution online.

Create a basic framework app

Even when building a server-side web app, you still need to create a basic framework app with the following required files and folders:

/manifest.json/assets   logo-small.png   logo.png/translations   en.json

You can generate these files using the Zendesk Command Line Interface (ZCLI). Refer to Creating starter files for a Zendesk app.

Note: ZCLI replaces the Zendesk Apps Tools (ZAT), which are in maintenance mode. To use ZAT instead, refer to Using the Zendesk App Tools (ZAT).

  1. If not already done, create a folder named tutorial_apps somewhere on your hard drive.

  2. Open your command-line interface (the command prompt in Windows or Terminal on the Mac) and navigate to the tutorial_apps folder.

  3. Run the following command at the prompt:

    $ zcli apps:new
  4. When prompted, enter the following information:

    • Directory name: app_local
    • Author's name: Your name
    • Author's email: Your email address
    • App name: Server-side App Tutorial

    ZCLI creates app starter files in the app_local folder.

  5. In a text editor, open manifest.json (/app_local/manifest.json).

    ZCLI records properties about your app in the manifest.json file. If you inspect the file, you'll see it specifies the host product (Zendesk Support), the app's location in the host (the ticket sidebar in the agent interface), and the path or URL of the page to display in the iframe (assets/iframe.html).

    To display server-side content, you'll need to update the iframe URL.

  6. Replace the ticket_sidebar property's url value with the following:

    "location": {  "support": {    "ticket_sidebar": {      "url": "http://localhost:8080/sidebar",      "flexible": true    }  }},...

You'll need to change the URL again when you deploy the web app.

Create a web application

To develop and test the web application, you'll need Python and a pair of Python libraries, as described next.

Install Python

Install version 3 of Python on your computer if you don't already have it. Python is a powerful but beginner-friendly scripting and programming language with a clear and readable syntax. Visit the Python website to learn more. To download and install it, see

Install Requests

The Requests library simplifies making HTTP requests in Python. Use the following pip command in your command-line interface to download and install it:

$ pip3 install requests

If you get an error and have Python 3.3 or earlier, try pip install requests instead.

If you have any other problems, see the Requests instructions.

Install Bottle

Bottle is a micro web framework for Python. Use the following pip command to download and install it:

$ pip3 install bottle

If you get an error and have Python 3.3 or earlier, try pip install requests instead.

If you have any other problems, see the Bottle instructions.

Set up the web application

  1. In your tutorial_apps folder, create a folder named app_remote.

    You can call it anything you want, but app_remote puts it close to the app_local folder in the file browser.

  2. In the new app_remote folder, create a text file named

  3. Open in a text editor and paste the following lines in the file:

    from bottle import route, run
    # app code goes here
    run(host='localhost', port=8080, debug=True)

    The first line imports the Bottle route and run methods to create routes to pages and run the web application.

    The Bottle framework has a built-in development server you can use to test your changes. The run() method starts and runs the web server on port 8080.

    To learn more about the framework, see Bottle: Python Web Framework on the Bottle website.

Python gotchas

  • Indentation matters in Python. When copying the examples in this tutorial, make sure to indent lines exactly as shown. So far all the lines are flush with the left margin.

  • Indent with 4 spaces, not a tab. Python will stop executing and report an indentation error if it encounters a tab character.

Display server-side content in the Zendesk app

To display server-side content in the iframe app in Zendesk Support, simply create a route in the web app to handle requests from the iframe. To refresh your memory, Zendesk Support makes an intial request to http://localhost:8080/sidebar, the URL specified in your manifest.json file.

  • In, replace the # app code goes here comment with the following route:

    @route('/sidebar')def send_iframe_html():    return '<p>App content from the server</p>'

    The send_iframe_html() function returns the line of HTML in response to any HTTP request to the /sidebar route. (You can name the function anything you want.)

You can test it immediately with the built-in development server in Bottle:

  1. In your command-line interface, navigate to the app_remote folder.

  2. Run the following command to start the local server:

    $ python3
  3. Wait a moment to allow the server to start, then open http://localhost:8080/sidebar in a browser.

    You should see the following HTML page:

You can already test the app in the Zendesk Support agent interface:

  1. Make sure your Bottle server is still running. Zendesk Support will request the initial page from it.

  2. Open a new command-line window and navigate to the app_local folder.

  3. Run the following command to start the Zendesk Support local server:

    $ zcli apps:server
  4. In a web browser, navigate to any ticket in Zendesk Support. The URL should look something like this:

  5. Append ?zcli_apps=true to the ticket URL, and reload the page. The URL should look like this:

  6. If you're using the Chrome browser, the content of your app may be blocked. Click the lock icon on the left side of the address bar and select Site settings. On the Settings page, scroll to the Insecure Content section and select Allow.

    Click the lock icon in the address bar:

    On the Settings page, allow insecure content:

    Note: Firefox doesn't block app content but Safari does and has no option to disable blocking. You must use Chrome or Firefox to work with the local ZCLI server.

The browser should reload the page and display the app (such as it is) in the ticket sidebar. It should contain the HTML served by the Bottle web server.

That's all there is to displaying server-side content in a Zendesk app. The rest is just the details of building the web app, including creating pages that can access both external and framework APIs.

In this tutorial, you built and ran a web app that displayed content in the iframe in Zendesk Support. In the next tutorial, you'll learn how to request and display external data in Zendesk Support. Get started: Part 3 - Access external APIs.