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.
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.
Log into your Jira instance as an admin. Click the admin dropdown
and 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.
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.
On the Apps page click New app and use the following settings in the modal dialog:
Click Create app to complete this step.
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 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.
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.
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.
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:
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.
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.
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.
Complete this step by clicking Save.
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.
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.
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!