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
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 |
Workspace data |
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.
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:
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!
Last updated
