Setting up

Overview

Before you start with the installation it may be helpful to get a quick overview of what exactly you are installing and how the different components fit together.

The Intercom for Jira Data Center/Server app consists of two parts:

(1) Jira features that enable your team to link Intercom conversations to Jira issues, see conversations in the issue view, and have automation features to simplify your workflow. For these features, the app makes requests to the Intercom API to fetch data from your connected Intercom workspace.

(2) An Intercom Inbox app that allows you to create, link and comment Jira issues directly from within your Intercom Inbox. You will set up this app yourself during the process described below.

It is important to note that both of these parts are contained in the Jira app that you install from the Atlassian Marketplace. Your Jira instance will handle requests, with the help of Intercom for Jira, from your Intercom Inbox app.

Installation

Log into your Jira instance as an admin. Click the admin dropdownand choose Manage apps (1) (Add-ons in older Jira versions). The Find new apps (2) screen loads.

Use the search box to locate Intercom for Jira (3) and click Install (4).

Once Intercom for Jira is installed, go to Manage apps and expand Intercom for Jira. Please take note of your installed app version (1) you will need later when you create your own Intercom app. After that, click Get started (2). This will guide you through the setup steps.

Create your own Intercom app

In this section, you will create and configure your own Intercom app. This will provide you with the required secrets to create a connection from your Jira projects to Intercom. You will have to do this only once.

1. Log in to Intercom Developer Hub

Go to https://developers.intercom.com/ and click on the menu called Your Apps in the top right corner (if you are not logged in to Intercom you will be redirected to the login page).

2. Create your own Intercom app

On the Apps page click New app and use the following settings in the modal dialog:

Setting	Value
App name	Jira (or anything you like really)
Workspace	Intercom workspace that you would like to connect to Jira (you can add the app to other workspaces later)
App Type	Internal integration

Click Create app to complete this step.

3. Configure API version

To make sure your Intercom app can communicate with the Jira app please check that you have the correct API version configured. The following table shows which Jira app version goes with which Intercom API version.

Jira app version	Intercom API version
all versions	1.3 (2019-06-05)

Jira app upgrade may require you to upgrade Intercom API version

At the time of this writing, all Jira app versions require the same Intercom API version. However, as Intercom and ToolsPlus develop new features you may be required to upgrade the Intercom API version as part of the Jira app upgrade process.

We will make sure to highlight in the release notes clearly if you are required to upgrade the Intercom API version for a new Jira app version.

To configure the API version go to Basic information (1) in the left-hand menu. Then click Change version (2) which opens a dialog. Select the correct version from the dropdown and click Change version to complete the dialog.

4. Configure permissions

By default, your app will have quite a broad range of permissions. You can either leave those as they are and continue with the next step or configure the minimal set of required permissions.

Jira app upgrade may require you to add more permissions

If you choose to configure minimal permissions, note that you may have to add more later as ToolsPlus or Intercom adds new features to the app.

We will make sure to highlight in the release notes clearly if you are required to upgrade permission for a new Jira app version.

To configure permissions click Authentication (1) in the left-hand menu. Then click Edit in the top right corner.

Select at least the following permissions and click to finish:

People and conversation data
✅ Read and list users and companies
✅ Read conversations
✅ Write conversations

Workspace data
✅ Read admins
✅ Read one admin
✅ Read data when entered into the app

If you have decided to go for the minimal scopes, or if you have made any changes to the scopes, make sure you regenerate your access token to represent the new scopes. To do this, click on Test & publish > Your workspaces (1) in the left-hand menu and then click Regenerate token (2) for any token with outdated scopes.

5. Configure Inbox endpoints (optional)

The Jira app comes with a built-in Intercom integration. If you would like to use it, follow the steps below to get it set up. If you prefer not to use it or want to configure it later feel free to skip this step.

Requires Jira on HTTPS

To use the built-in Intercom app your Jira instance must be accessible over HTTPS. Read more on how to configure HTTPS

Still in the Developer Hub, go to Configure > Canvas Kit (1) in the left-hand menu, then click For teammates (2). Select the checkbox Add to conversation details (3) and enter the following webhook URLs (4, 5):

Please make sure that you use the correct Jira base URL

Some Jira instances are configured to run under my-jira-instance.com others include a context path as shown in the example above, my-jira-instance.com/jira.

Read more on configuring the base URL.

URL	Value
Initialize flow URL	https://<your-jira-base-url.com/jira>/rest/intercom/latest/app/inbox/initialize
Submit flow URL	https://<your-jira-base-url.com/jira>/rest/intercom/latest/app/inbox/submit

Complete this step by clicking Save.

6. Copy your app's access token and client secret

After you have configured your app, take note of the app's access token and client secret you will need those in the next section to configure the Jira app.

App Secret	Location in Developer Hub
Access token	Configure > Authentication
Client secret	Configure > Basic information

Setup a Connection to Intercom

1. Open Intercom integration settings for your Jira project

If you have followed the on-boarding steps at the end of the Jira app installation you will most likely already have the Intercom integration settings open. In this case, you can skip this step.

If you do not have the settings open, follow the steps below:

Log in to Jira as an administrator. Click the admin dropdown(1) and choose Projects, then select the project that you would like to connect to Intercom. Click on Intercom integration (2) in the left-hand menu. This loads the Intercom integration settings page.

2. Configure Intercom app's secrets

We assume you have already created and configured your own Intercom app. If you have not done this yet, follow the steps on how to create and configure your own Intercom app.

Is it okay to use access token and client secret to set up a connection?

The Intercom documentation mentions that you should not use access tokens if any Intercom integration asks for them. However, to make Intercom for Jira Data Center/Server work, we require you to configure an access token and client secret. These secrets remain your own and will not be stored anywhere else other than your own Jira instance. This practice has been approved by Intercom.

From Intercom copy and paste your Intercom app's access token (1) and client secret (2) to their respective fields, then click Connect (3).

🎉 That's it, you are ready to go!