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 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 setup 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.
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 in 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.
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).
On the Apps page click New app and use the following settings in the modal dialog:
Jira (or anything you like really)
Intercom workspace that you would like to connect to Jira
(you can add the app to other workspaces later)
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 version
Intercom API 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.
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.
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
✅ 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.
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):
Initialize flow URL
Submit flow URL
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.
Location in Developer Hub
Configure > Authentication
Configure > Basic information
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.
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.
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!