In this five-part tutorial series, you'll learn how to build a Zendesk Chat app from start to finish. The app you'll build is called Learn More. This tutorial covers the first steps to building the app:
The other tutorials in the series teach you how to build and install the app:
- Part 2 - Designing the user interface
- Part 3 - Creating and inserting templates
- Part 4 - Getting data
- Part 5 - Installing the app in Zendesk Chat
Because the tutorials build on each other, tackle them in order and finish each tutorial before moving on to the next one.
Planning the app
You should have a good idea of how your app will look and work before you start working on it. The app you'll build in this tutorial is called Learn More and is designed to let a chat agent send a visitor links to more information about any subject. It'll have a simple interface consisting of a search box and button. Here's a mockup of the user interface:
The app will appear in the sidebar on the right side of the agent's chat interface.
The app should work as follows:
At any time during a chat, the agent enters a subject in the app's search box and clicks Search
The app makes an HTTP request to the MediaWiki API for the top 3 articles on Wikipedia about the subject
The app inserts links to the 3 articles directly in the chat's text area
The agent presses Enter to send the links to the visitor
Installing the Zendesk app tools
In this section, you'll install the Zendesk app tools (also known as the ZAT tools). The tools let you perform the following tasks:
- Automatically create all the necessary files and folders for a new app
- Test your app locally in a browser
- Validate your app
- Package your app for upload
gem update zendesk_apps_toolson the command line, then skip ahead to Creating the app files.
Installing the tools is a one-time task. Once installed, you can use the ZAT tools for all your Zendesk app projects. See the known issues article if you run into any problems installing or using the tools.
You use the command prompt in Windows or Terminal in Mac OS X to install the tools. In Mac OS X, double-click the Terminal application in your Applications/Utilities folder. To open the command prompt in Windows, open the Start Menu, type cmd in the search box, and press Enter.
ZAT is a Ruby gem -- a self-contained package of Ruby code that extends Ruby. You don't need to know Ruby to use the tools, but you do need to install Ruby to install the gem. ZAT supports Ruby 2.0 or later.
It’s possible that Ruby is already installed on your system. In your command-line interface (the command prompt in Windows or Terminal in Mac OS X), run the following command to see if Ruby is installed:
$ ruby -v
You should see something like this:
If you get an error, Ruby is not installed. If the result is a Ruby version earlier than 2.0, you'll need to update it. If the result is Ruby 2.0 or better, you don't need to do anything. Your version of Ruby is supported. Jump to Installing the ZAT gem.
Installing Ruby in Windows
For a more detailed version of this procedure, see Installing and using the Zendesk apps tools.
- Go to http://rubyinstaller.org/downloads/ and download the latest stable Ruby installer.
- Double-click the downloaded file and follow the instructions.
- Depending on the version of Ruby you installed, download and install the Ruby Development Kit (DevKit) from the same page. See Which Development Kit? on the RubyInstaller page.
- Test the installation by checking the version number at the command line:
C:\> ruby -v
If the test is successful, go to Installing the ZAT gem below.
Installing Ruby in Mac OS X
Installing the ZAT gem
After installing Ruby, run the following command in your command-line interface:
$ gem install zendesk_apps_tools
The ZAT gem and a number of supporting gems are installed, along with related documentation. You should see status messages like the following:
Creating the app files
After installing the Zendesk app tools, you're ready to start building the Chat app. The first step is to create the starter files for a new app called Learn More in a folder called learn_more.
Create the app files
- In your command-line interface (the command prompt in Windows or Terminal in Mac OS X), navigate to the folder where you want the app files to be saved in a subfolder.
Use the cd command (for change directory) to navigate to a child folder. Example:
$ cd projectsTip: To go back up to a parent directory, use cd followed by a space and two periods. Example:
- Run the following ZAT command:
$ zat new
If you get an error that the command doesn't exist, make sure the Zendesk app tools are installed. See Installing the Zendesk apps tools.
- At the prompts, enter the following values:
- author's name - your name
- author's email - your email
- author's url - your website url if you have one, or press Enter to leave it blank
- app name - Learn More
- iFrame URI - press Enter to leave it blank. You'll use the default local iframe file
- directory name - learn_more
The ZAT tool creates and lists the directory and files. The window should look as follows in Mac OS X:
- Open your file browser and navigate to the files.
The folder contains an assets and translations folder, plus a manifest.json and README.md file. You can add as many files as you need when you're building your app, but for now it's all you need to start building an app.
Because it's an iframe app, you can host the app in Zendesk Chat or on a remote server with any technology stack you prefer. If you're only using client-side technologies like Handlebars and jQuery, as you will be here, you can simply host it in Zendesk Chat.
Everything is in place to start building. In the next tutorial, you'll learn more about the HTML file to be iframed into the chat window. You'll change the heading, add a footer, and add some styles to meet the design requirements specified in Planning the app above. Get started: Part 2 - Designing the user interface.