Part 1: Build a Zendesk app with OAuth

In this tutorial series, you'll build a Zendesk integration for Slack. The integration listens forTicket Createdevents in Zendesk. When it detects an event with a specific ticket priority, the integration posts a related message to a provided Slack channel.

As part of the series, you'll also build a Zendesk app. The app's user interface (UI) lets admins connect the integration to their Zendesk and Slack instances. The app also lets admins configure settings for the integration. The app uses Zendesk Integration Services (ZIS) APIs to manage the connections and configurations.

This tutorial covers the first steps for setting up the integration and the Zendesk app. Other tutorials in the series teach you how to finish building the app and install the integration:

• Part 2: Connect to Slack
• Part 3: Add a configuration UI
• Part 4: Install the integration

For on-demand training related to this tutorial series, check out the freeBuild a Custom Integration With ZIStraining course.

Disclaimer: Zendesk provides this article for instructional purposes only. The integration and examples are not meant for production environments. Zendesk does not provide support for this integration or app. Post any issue in theZendesk developer communityor search for a solution online.

What you'll need

To complete this tutorial, you’ll need the following:

• A Zendesk account for testing. ZIS is supported on the Zendesk Suite Growth plan or above, and the Support Professional plan or above. To get a free eligible account for testing, seeGetting a trial or sponsored account for development.

• Be an admin on the account or have access to someone who is an admin. The admin can give you admin access. Refer toSetting roles and access in Zendesk Admin Center.

• A Slack workspace for testing. If you need a workspace, refer toCreate a Slack workspace.

• The Zendesk Command Line Interface (ZCLI). To install or upgrade ZCLI, refer toInstalling and updating ZCLI. ZCLI replaces the Zendesk Apps Tools (ZAT), which are in maintenance mode. To use ZAT instead, refer toInstalling and using ZAT.

• Familiarity with ZIS and theZendesk Apps framework (ZAF). Before starting, we recommend you complete the following tutorials:

  • Building your first ZIS integration
  • Building your first Support app

• Familiarity with basic OAuth 2.0 concepts, such as OAuth flows and access tokens. To learn more about OAuth, check outUsing OAuth authentication with your application.

Register the integration

First, register the integration's name using theCreate Integrationendpoint.

Integration names must be globally unique. For this tutorial, use an integration name of{subdomain}_zendesk_to_slack. Replace{subdomain}with your Zendesk subdomain.

1. 在你的逗号nd-line interface, run:

                  
   
                   
   curl-XPOSThttps://{subdomain}.亚博.com/api/services/zis/registry/{subdomain}_zendesk_to_slack \-u{email_address}:{password}\-H"Content-type: application/json"\-d'{"description": "An example integration"}'
                  

   The integration uses an OAuth connection to make Zendesk API requests on the admin's behalf. To create the connection, your Zendesk app uses ZIS APIs to start an OAuth flow. To start an OAuth flow, ZIS first requires anOAuth client. The client contains details used to pass data between ZIS and the other system during the OAuth flow.

   When you register an integration, the request automatically creates an OAuth client for Zendesk. The client is named "zendesk." The response contains information about your integration and its OAuth client. For example:

                  
   
                   
   {"description":"An example integration","jwt_public_key":"***RSA Public Key to save***","zendesk_oauth_client":{"id":12345,"identifier":"zis_{subdomain}_zendesk_to_slack","secret":"***secret***"}}
                  

2. Save the response securely. You’ll use these details later in this tutorial.

Create a Zendesk app

Next, use ZCLI to create starter files for a Zendesk app named Zendesk to Slack Notifier.

1. 在你的逗号nd-line interface, navigate to the folder you'll use to store the app. For example:

                  
   
                   
   cdprojects
                  

2. In the folder, run the following ZCLI command:

                  
   
                   
   zcli apps:new
                  

3. At the prompts, enter the following values:

   • Directory name:zendesk_to_slack_app
   • Author's name: Your name
   • Author's email: Your email address
   • Author's website: Leave blank and press Enter.
   • App name:Zendesk to Slack Notifier

   ZCLI creates app starter files in thezendesk_to_slack_appfolder.

Set app location

Update your app to run in the nav bar of the Zendesk Support UI. This location lets admins access the app from any Support page.

1. In thezendesk_to_slack_appfolder, openmanifest.jsonin your text editor.

2. Replace thelocationproperty with the following:

                  
   
                   
   "location":{"support":{"nav_bar":"assets/iframe.html"}},
                  

3. Savemanifest.json.

Test the app

Your app doesn't do much yet, but you can already use ZCLI to run it. Run your app often to test changes.

1. 在你的逗号nd-line interface, navigate to thezendesk_to_slack_appfolder. For example:

                  
   
                   
   cdprojects/zendesk_to_slack_app
                  

2. Start a ZCLI local web server by running the following command:

                  
   
                   
   zcli apps:server
                  

   After a moment, a status message appears informing you that the server has started.

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

3. 在浏览器的私人或隐身窗口中,团体n in to Zendesk Support and go to the Agent Dashboard. The URL should look like this:

   https://{subdomain}.zendesk.com/agent/dashboard

4. Append?zcli_apps=trueto the URL and press Enter. The URL should now look like this:

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

   An app icon is displayed in the left nav bar.

   

5. Click the icon to launch the app.

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

   

Connect to Zendesk

The app's UI should include aConnect to Zendeskbutton. When an admin clicks the button, the app uses ZIS APIs to start an OAuth flow with Zendesk. When done, the OAuth flow sends a Zendesk access token to ZIS for storage.

Add a "Connect to Zendesk" button

1. In the app'sassetsfolder, openiframe.html. Replace the file's contents with the following:

                  
   
                   
   <html><head><metaname="viewport"content="width=device-width, initial-scale=1"/><linkhref="https://cdn.jsdelivr.net/combine/npm/@zendeskgarden/css-bedrock,npm/@zendeskgarden/css-grid,npm/@zendeskgarden/css-buttons,npm/@zendeskgarden/css-forms,npm/@zendeskgarden/css-utilities"rel="stylesheet"/>head><body><divclass="u-m u-fg-grey-800"><divclass="u-mb"><divclass="row"><divclass="col-6"><divclass="c-txt u-mb"><buttonid="btnConnect"class="c-btn c-btn--primary">Connect to Zendeskbutton>div>div>div>div>div><scripttype="text/javascript"src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js">script><scripttype="text/javascript"src="bootstrap.js">script><scripttype="text/javascript"src="connect.js">script>body>html>
                  

   The HTML includes the following:

   • A stylesheet for the app's UI. This app usesGarden, Zendesk's design system. For simplicity, the app uses Zendesk Garden'sCSS components. For a real-world app, we recommend using Garden'sReact components.

   • Markup for theConnect to Zendeskbutton.

   • A