DocumentationAPI Reference

Part 2: Connect to Slack

This tutorial is part of a series that builds a Zendesk integration for Slack:

In the previous tutorial, you created a Zendesk app with a Connect to Zendesk button. The button lets admins connect the integration to their Zendesk instance.

In this tutorial, you'll add a Connect to Slack button to the app. This button lets admins connect the integration to a Slack workspace.

Set up Slack

When complete, the integration will post messages to a Slack channel. To post messages, the integration needs a Slack app.

Create a Slack app

To start, create a Slack app named Zendesk Ticket Bot.

  1. Go to https://api.slack.com/apps and click Create an App.

  2. In the modal, click From scratch.

  3. Enter Zendesk Ticket Bot as the app name. Then select a workspace.

  4. Click Create App.

    The Basic Information page for your Slack app is displayed.

  5. Scroll down the page to the App Credentials section.

  6. In the Client Secret field, click Show.

  7. Save the client ID and secret in a secure place. You'll use them later in this tutorial.

Add a scope

Next, add the chat:write scope to your Slack app. This scope gives the app permission to post messages.

  1. In the left sidebar, click OAuth & Permissions.

    The OAuth & Permissions page is displayed.

  2. Scroll down to the Scopes section.

  3. Under Bot Token Scopes, click Add an OAuth Scope.

  4. In the field, type chat:write and press Enter.

Install the app to your workspace

Next, install the Slack app to your workspace. This lets the app post messages in the workspace.

  1. Scroll up to the top of the OAuth & Permissions page.

  2. Under OAuth Tokens for Your Workspace, click Install to Workspace.

    The Slack OAuth page opens in a new tab.

  3. Click Allow.

    The OAuth page closes and redirects you back to the OAuth & Permissions page.

Connect to Slack

When an admin clicks the Connect to Slack button, the app uses ZIS APIs to start an OAuth flow with Slack. When done, the OAuth flow sends a Slack access token to ZIS for storage. Your integration can then use the stored token to make Slack API requests.

Add a redirect URL

Set a default redirect URL for your Slack app. During an OAuth flow, Slack sends ZIS an verification code at this URL. Later in the OAuth flow, ZIS exchanges the verification code for an access token.

  1. On the OAuth & Permissions page, scroll down to the Redirect URLs section.

  2. Click Add New Redirect URL.

  3. In the field, enter:

    https://zis.zendesk.com/api/services/zis/connections/oauth/callback

  4. Click Add.

  5. Click Save URLs.

Add a Slack OAuth client

To start an OAuth flow, ZIS first requires an OAuth client object. The client contains details used to pass data between ZIS and the other system during the OAuth flow.

For third-party systems, such as Slack, you need to create the client using the Create OAuth Client endpoint.

  1. In your command-line interface, run the following curl request. Replace:

    curl -X POST https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{subdomain}_zendesk_to_slack \  -H "Authorization: Bearer {access_token}" \  -H "Content-type: application/json" \  -d '  {    "name": "slack",    "client_id": "{slack_client_id}",    "client_secret": "{slack_client_secret}",    "default_scopes": "chat.postMessage",    "auth_url": "https://slack.com/oauth/v2/authorize",    "token_url": "https://slack.com/api/oauth.v2.access"  }'

    The request creates an OAuth client named "slack." If successful, the response contains the client's universally unique ID (UUID).

Add a "Connect to Slack" button

Next, add a Connect to Slack button to your Zendesk app.

  1. In the Zendesk app's assets folder, open iframe.html. Add the following HTML directly after the <div> tag containing the Connect to Zendesk button.

    ...<div class="c-txt u-mb">  <button id="btnConnect" class="c-btn c-btn--primary">    Connect to Zendesk  </button></div><div class="c-txt u-mb">  <button id="btnConnectSlack" class="c-btn c-btn--primary">    Connect to Slack  </button></div>...

  2. In bootstrap.js, add the following:

    ...      startOAuth(integrationName, subdomain);    });
  // Bind button to start a Slack OAuth flow  document    .getElementById("btnConnectSlack")    .addEventListener("click", function () {      startSlackOAuth(integrationName, subdomain);    });...

    The code binds the Connect to Slack button to the startSlackOAuth function.

  3. In connect.js, add the following to the end of the file:

    ...
// startSlackOAuth initiates a Slack OAuth flowfunction startSlackOAuth(integrationName, subdomain) {  let data = JSON.stringify({    name: "slack", // the name the obtained access token    oauth_client_name: "slack",    oauth_url_subdomain: subdomain,    origin_oauth_redirect_url: window.location.href,    permission_scopes: "chat:write",  });
  let request = {    type: "POST",    url: "/api/services/zis/connections/oauth/start/" + integrationName,    contentType: "application/json",    data: data,  };
  client.request(request).then(    function (response) {      console.log("Slack OAuth started");      authorize(response.redirect_url);    },    function (response) {      console.log("Failed to start Slack OAuth: ", response);    }  );}

    The code defines the startSlackOAuth function. When called, startSlackOAuth makes a Start OAuth Flow request to kick off an OAuth flow with Slack. The request uses the "slack" client you created earlier. When the OAuth flow completes, ZIS stores the resulting access token in an OAuth connection.

    The Start OAuth Flow endpoint requires a name for the connection. startOAuth uses a connection name of "slack."

  4. Save iframe.html, bootstrap.js, and connect.js. Then refresh the app.

    Your app now displays a Connect to Slack button.

Get a Slack access token

Next, use your Zendesk app's Connect to Slack button to start an OAuth flow with Slack.

  1. In your app, click Connect to Slack.

    A workspace sign-in page opens in a new tab.

  2. Enter your workspace's subdomain and click Continue.

    A Slack sign-in page is displayed.

  3. Sign in to Slack using your preferred method.

    A Slack OAuth page is displayed.

  4. Click Allow.

    The OAuth page closes and redirects you back to the OAuth & Permissions page.

Verify the Slack access token

Next, use a Show OAuth Connection request to get the "slack" OAuth connection you created. This lets you verify that your integration can use the connection to authenticate Slack API requests.

In your command-line interface, run the following curl request. Replace {access_token} with the OAuth access token you got in Verify the Zendesk access token.

curl -X GET https://{subdomain}.zendesk.com/api/services/zis/connections/{subdomain}_zendesk_to_slack?name=slack \  -H "Authorization: Bearer {access_token}"

The response contains details about the "slack" connection, including its access token. For example:

{  "uuid": "***uuid***",  "name": "slack",  "zendesk_account_id": 12345678,  "integration": "example_zendesk_to_slack",  "permission_scope": "chat:write",  "access_token": "***access token***",  "token_type": "bot",  "refresh_token": "",  "token_expiry": "0001-01-01T00:00:00Z",  "oauth_access_token_response_body": "",  "oauth_url_subdomain": "example",  "created_by": "1234567890123",  "created_at": "2099-05-16T15:33:19Z"}

In the next tutorial, you'll add an app UI to let admins set the ticket priority and Slack channel for your integration. Refer to Part 3: Add a configuration UI.