Zendesk app quick start

In this 10-minute quick start, you'll build and locally run a Zendesk app. The quick start introduces you to the tools and workflows commonly used for Zendesk app development. When you're finished, you'll have a basic app that displays a personalized greeting in the ticket sidebar of Zendesk Support.

What you'll need

To complete this quick start, you'll need the following:

• Node.js 14.17.3 or later

• A Zendesk account with the Zendesk Suite Growth plan or above, or the Support Professional plan or above. To get a free eligible account for testing, see Getting a trial or sponsored account for development.

• A web browser, such as Chrome or Firefox, that allows mixed HTTP and HTTPS content. You'll need this browser to run the app locally. Safari doesn't support mixed content and won't allow you to run Zendesk apps locally.

Creating the app files

To start, use the Zendesk Command Line Interface (ZCLI) to create starter files for the app. ZCLI is a command-line tool that lets you build and test Zendesk apps locally.

To create the app files

1. In your computer's terminal, navigate to the folder where you want to store the app. Example:

   cd projects

2. In the folder, run:

   npx @zendesk/zcli apps:new

   npx lets you run some ZCLI commands without installing the ZCLI package first.

3. At the prompts, enter the following values:

   • Directory name: hello_world
   • Author's name: Your name
   • Author's email: Your email address
   • Author's website: Leave blank and press Enter
   • App name: Hello World

   ZCLI creates starter files for the app in the hello_world folder.

Checking the app location

An app can run in one or more locations of a Zendesk product. For example, a Support app may run in the ticket sidebar, the nav bar, or both. Each location runs a separate instance of the app in an iframe.

You can configure an app's locations using the manifest.json file's location property. The property also specifies the source URL of each location's iframe.

To check the app location

1. In the hello_world folder, open manifest.json in your text editor.

2. Ensure the location property contains the following:

   ...
   "location": {
     "support": {
       "ticket_sidebar": {
         "url": "assets/iframe.html",
         "flexible": true
       }
     }
   },
   ...

   The support and ticket_sidebar keys ensure the app runs in the ticket sidebar of Zendesk Support. The url value ensures the sidebar app's iframe displays content from the assets folder's iframe.html file.

3. Close manifest.json.

Running the app locally

Next, use ZCLI to run the app locally. This lets you test the app while making changes.

To run the app locally

1. In your terminal, navigate to the hello_world folder. Example:

   cd projects/hello_world

2. Use ZCLI to start a local web server for the app. Run:

   npx @zendesk/zcli apps:server

   Note: To stop the server, press Ctrl+C.

3. Open an incognito or private window in your browser.

   An incognito or private window doesn't cache files used by the app. Cached files may prevent the browser from displaying the app's latest changes.

4. Sign in to Zendesk Support and go to the Agent Workspace. From the workspace, open a ticket. The URL should look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}

5. Append ?zcli_apps=true to the URL and press Enter. The URL should now look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}?zcli_apps=true

6. Click the Apps icon.

   

   The app displays a "Hello, World!" heading.

   

Fetching the user's name

You can use Zendesk Apps framework (ZAF) APIs to access Zendesk resources from an app. For example, you can use ZAF APIs to fetch the current user's name or add a comment to a ticket.

To access ZAF APIs, a Zendesk app uses a JavaScript library called the ZAF SDK. The SDK includes a ZAF client. You can use this client's methods to make ZAF API calls.

To complete the app, use the ZAF client to fetch the current user's name. Then add JavaScript code to display the name in the app.

To fetch and display the user's name

1. In the app's assets folder, open iframe.html in your text editor.

2. Replace the <h2> tag with the following:

   ...
   <h2 class="u-semibold u-fs-xl">Hello, <span id="name">World</span>!</h2>
   ...

   This change wraps the "World" text in a <span> tag. Later, you'll update the app to dynamically replace this text with the current user's name.

3. Ensure the file's <body> contains the following <script> tag:

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

   The tag imports the ZAF SDK.

4. Ensure the <body> also contains the following <script> tag:

   <script>
     // Initialise Apps framework client. See also:
     // https://developer.zendesk.com/apps/docs/developer-guide/getting_started
     var client = ZAFClient.init();
     ...
   </script>

   The script tag sets up an instance of the ZAF client. You can use the client's methods to access ZAF APIs from the app.

5. Add the following JavaScript to the <script> tag:

   <script>
     // Initialise Apps framework client. See also:
     // https://developer.zendesk.com/apps/docs/developer-guide/getting_started
     var client = ZAFClient.init();
     client.invoke("resize", { width: "100%", height: "200px" });
   
     async function displayUserName() {
       const response = await client.get("currentUser.name");
       const name = response["currentUser.name"];
       const span = document.getElementById("name");
       span.innerText = name;
     }
   
     displayUserName();
   </script>

   The code uses the ZAF client's get() method to fetch the user name from the currentUser object. The code then replaces the text of the <span> tag with this user name.

6. Save iframe.html.

7. In your browser, reload the Agent Workspace page. The app now displays your user name.

   

Next steps

Congratulations! You've created a basic app for Zendesk support. As a next step, consider the following tasks:

• Install and configure ZCLI. An installed, authenticated version of ZCLI lets you package and upload the app to your Zendesk instance. See Using ZCLI.

• Use the v2 REPL app to explore more of the ZAF client's capabilities. See Test drive the Apps framework.

• For a more in-depth app tutorial, complete the Building your first Support app tutorial series.