Sync attachments from Intercom® conversations — the screenshots, images, and videos your customers send — into Jira issues as native Jira attachments.
Setup takes about 15 minutes and has to be done once, by someone who is both a Jira administrator and able to create an app in Intercom's Developer Hub.
You will need:
Jira Cloud, with site administrator access.
A paid Intercom subscription. Intercom is a separate product, sold and licensed by Intercom, Inc. under your own agreement with them. It is not included with this app, IDEAL WORKS does not resell it, and this app does nothing without it. Your workspace needs to be on a plan that lets you create an app in Intercom's Developer Hub.
An Intercom workspace hosted in Intercom's US region. This version connects to
api.intercom.io only. Workspaces hosted in the EU or Australia use different Intercom API
endpoints and are not supported yet — connecting will fail with "That token was rejected
by Intercom" even though the token is correct. Support for those regions is planned.
Steps 1, 4 and 5 all happen inside Intercom's Developer Hub. If your Intercom account cannot reach it, ask whoever administers Intercom to do those three steps with you — step 5 in particular, because leaving its Topics empty is the most common reason setup appears to fail.
A decision about internal notes. The app copies every attachment on a linked conversation, including files attached to internal notes that the end customer never sees. Those files land on the Jira issue, visible to everyone who can view it. There is no setting to exclude them. If that matters for a project, decide it before you link conversations there.
The Jira Create attachments permission on the project, for everyone who will link conversations or sync files — not just the admin doing the setup. Without it the Support attachments panel shows a permission warning and nothing else: no link field, no Sync button. A Jira admin grants it under Project settings → Permissions.
Decide who gets this permission before you finish setup. The app checks that permission on the Jira issue; it cannot check anything on the Intercom side, because it has no way to match a Jira account to an Intercom teammate. Anyone holding Create attachments on a project where this panel appears can type in any conversation id from your workspace — as long as it is not already linked to another issue — and bring that conversation's files onto an issue they can see. On a project with external contractors, that is worth thinking about first.
You will move two different values from Intercom into Jira. They live on two different pages and are easy to confuse:
| Value | Where it lives in Intercom | What it is for |
|---|---|---|
| Access Token | Developer Hub → your app → Authentication | Letting the app read conversations and download attachments |
| Client Secret | Developer Hub → your app → Basic information | Proving that incoming webhooks really came from Intercom |
Jira attachment sync.read_conversations (shown as Read conversations) and Read one admin.
Without read_conversations the app cannot read attachments. Without Read one admin
the connection check in step 3 cannot identify your workspace and rejects the token with
That token was rejected by Intercom, even when the token is perfectly valid.
A brand-new app has every permission switched on, so if you have not narrowed anything
yet, both are already there. Only these two are needed; you can switch the rest off.You are done when: the app exists and shows an Access Token on the Authentication page.
Install Support Attachment Sync from the Atlassian Marketplace onto your Jira site.
You are done when both of these appear:
Jira Settings (gear icon) → Apps → Support Attachment Sync in the left sidebar
A Support attachments panel on a Jira issue. Jira does not show it until you add it, and you have to add it on every issue you want to use it on. On the issue, click the apps button (the round icon next to +, under the title) and choose Support attachments. The panel then appears at the bottom of that issue and stays there.
This is Jira's behaviour, not a setting in this app, and there is nothing the app can do about it. Adding the panel to one issue does not add it to the next issue you create — not even one of the same work type. If you open a brand-new issue and see no panel, the app is installed correctly; you just have not added the panel to that issue yet.
⚠️ The text boxes on these screens have no visible label in this release. The code sets one, but it does not render, and screen readers get no name for them either. Each section has exactly one input, so which box to use is never ambiguous — but if you are looking for a box captioned Intercom access token, you will not find it. All three inputs are labelled in the next release.
You are done when: the status shows Connected followed by your Intercom workspace name and region.
If it refuses to connect:
| Message | What it means |
|---|---|
| That token was rejected by Intercom | First check that Read one admin is enabled on the Authentication page — without it the connection check cannot identify the workspace and produces this message even though the token is valid. Otherwise the token is wrong, expired, or was revoked — copy it again from the Authentication page — or your workspace is hosted outside Intercom's US region, which this version does not support yet. A correct token from an EU or Australia workspace produces exactly this message, so check the region before you re-copy the token a third time. |
| This token cannot read conversations | Usually the token lacks the read_conversations permission — enable it in step 1 and try again. In this release the same message also appears when Intercom is rate-limiting or briefly unavailable. If the permission is already on, wait a minute and press Connect again before changing anything. |
| Could not reach Intercom | The connection check could not reach Intercom at all. The token and its permissions are not the problem. Wait a minute and try again. |
| Could not connect. | The generic message. In this release it also covers two causes that are not about the token at all: the subscription is not yet active on this site — which appears briefly right after installing while the licence propagates, so check Jira Settings → Apps → Manage your apps — or Intercom returned something unexpected. Re-copying the token does not help with either. |
If you are not a Jira site administrator, this screen does not appear at all. In its place you see "Only Jira site administrators can configure this app. This screen handles Intercom credentials, so it is restricted." — there is no token field and no Connect button. Ask a Jira site admin to do steps 3 and 4.
The app checks both that the token works and that it can actually read conversations before saving it, so the most common cause of silent sync failures is ruled out here.
The Webhook signing secret section appears once a token is stored.
You are done when: the status next to Webhook signing secret shows Configured.
Why this matters: the webhook endpoint is a public URL that anyone can send requests to. This secret is what lets the app tell a genuine Intercom notification from a forged one. Until it is saved, every notification is discarded and no attachment will sync automatically.
The settings screen shows whether notifications are arriving and, if the signature does not match, says so — which is how you confirm you copied the right value.
Still on the Jira settings screen, find the Webhook endpoint section and copy the URL shown there.
This URL is unique to your Jira site. Do not reuse a URL from documentation or from another site, and do not share it.
In Intercom, go to Developer Hub → your app → Webhooks.
Paste the URL into Endpoint URL.
Subscribe to these two topics:
conversation.user.replied — a customer replies, often with a screenshotconversation.admin.replied — a teammate repliesYou do not need conversation.user.created. A brand-new conversation is not linked to
any Jira issue yet, so nothing would sync from it.
Save.
You are done when: Intercom accepts the endpoint and both topics show as subscribed.
The single most common setup mistake: registering the Endpoint URL but leaving Topics empty. Intercom then sends nothing at all, and the app looks broken while being perfectly healthy. If automatic sync does nothing, check Topics first.
The Intercom Webhooks page has a Send a test request button. Treat it as inconclusive. A test request carries no conversation, so nothing syncs from it either way, and whether it moves the Jira settings screen at all depends on exactly what Intercom sends. An unchanged screen after a test request is not evidence that anything is broken.
The check that does work today proves the whole path, and takes a minute:
You are looking for:
Last notification was accepted and queued for sync.
That one message means every part is right: Intercom can reach your endpoint, the URL belongs to your site, the signing secret matches, and the conversation is linked.
The messages that screen shows, so you can tell a healthy setup from a broken one:
| What the settings screen says | What it means | What to do |
|---|---|---|
| Last notification was accepted and queued for sync | Working normally | Nothing. |
| Intercom reached this endpoint, but has not sent a real notification yet | Intercom's connectivity check at registration arrived. Normal right after step 5 | Nothing. Go on to step 6, then reply on a linked conversation. ⚠️ This one is not signature-verified, so on its own it does not prove the signing secret is right. |
| …is not linked to any issue | A real notification arrived and the wiring works — you simply have not linked that conversation yet | Nothing. This is normal before step 6. |
| …was not signed with the Client secret saved here | A request reached your endpoint that this app could not verify. That is not proof your secret is wrong. The endpoint URL is unauthenticated by design, so anyone who has it can produce this line, and the screen shows only the most recent request. | Check whether attachments are still syncing first. If they are, your setup is fine — leave it alone. If they have stopped, re-copy the Client secret from Developer Hub → Basic information (redo step 4). It is a different value from the access token. |
| …before the signing secret was saved | You registered the webhook before doing step 4 | Do step 4, then reply on a linked conversation again. |
| No notification has arrived yet | Nothing has ever reached the endpoint | Topics are empty, or the Endpoint URL is missing or belongs to a different Jira site. |
A healthy-looking screen is not proof that automatic sync is running. If a notification arrives and the app cannot hand it to its internal queue, this release records nothing at all — the screen keeps showing the previous outcome. Intercom then stops delivering to the endpoint for fifteen minutes. See the status page; a manual Sync attachments recovers it.
The second row is worth reading twice: before step 6 there is nothing linked, so a real customer reply produces a warning-coloured "not linked to any issue" message. That is a working setup, not a broken one.
To find a conversation ID: open the conversation in Intercom and read it from the browser address bar — it is the long number at the end of the URL.
The app checks that the conversation actually exists in Intercom before saving the link, so a mistyped ID is rejected immediately rather than failing silently later.
You are done when: the panel shows Linked, the conversation ID, and a list of the attachments currently in that Intercom conversation.
If linking is refused:
| Message | What it means |
|---|---|
| Intercom is not connected yet | Step 3 has not been completed. The panel shows this instead of the link field. |
| That does not look like a conversation ID | Paste either the number alone or the whole conversation URL. Anything else is rejected before Intercom is contacted. |
| No conversation with that ID exists in Intercom | The ID is wrong, or the conversation belongs to a different Intercom workspace. |
| That conversation is already linked to <issue> | One conversation can belong to one issue only. Unlink it on the issue named in the message first. |
| You need permission to add attachments to this issue | Exactly that: the panel will not let you link or sync without the Jira Create attachments permission. A Jira admin grants it under Project settings → Permissions. |
| Could not check that conversation with Intercom | A temporary problem reaching Intercom. Try again. |
Click Sync attachments in the panel. The panel shows Syncing… while it runs and then reports the result. If a sync runs longer than about two minutes the panel stops updating and keeps showing Syncing… — the sync itself carries on and the files still arrive; reopen the issue to see the result. This is fixed in the next release.
From this point on, whenever someone replies in that Intercom conversation, the app syncs new attachments automatically. You do not need to press the button again.
Skipped — already in Jira. A file counts as already synced when its byte size matches
something on the issue and its name matches once a trailing (2)-style number is removed
from both sides. That removal is what stops a file the app itself renamed from being
uploaded again on the next sync.
⚠️ It has a side effect worth knowing before it bites you. The app cannot tell a number it
added from one a person typed. If someone has manually attached screenshot (2).png to the
issue, and a customer then sends a screenshot.png of exactly the same byte size, the app
treats them as the same file and skips the customer's one. The panel counts it under
skipped, so nothing on screen says the customer's file was the one dropped. Different byte
size is always uploaded, so this only happens when the sizes match exactly. The next release
limits the (n) removal to names this app generated itself.
A file with the same name but different contents is still uploaded, under a modified name
(image (2).png). Running a sync twice never creates duplicates.
Skipped — too large. Two limits apply and the app respects the stricter one:
Files without a name. Some attachments arrive from Intercom without a file name. The app generates one, adding a file extension based on the file type.
Failures are retried, but not forever. When an individual file fails for a temporary reason, that file is retried automatically with an increasing delay, up to five times — about fifteen minutes in all. Failures that cannot succeed on retry — a file above the Jira size limit, an expired token, a deleted issue — are not retried at all.
A sync that cannot start at all — Intercom or Jira briefly unavailable, or rate-limiting us — is retried as a whole instead, and in this release those retries carry on for up to about a day rather than stopping after five. Nothing is lost and no duplicates are created, but the panel goes on saying the sync is being retried.
The panel reports counts and state, not a per-file log:
Nothing syncs automatically, but the manual button works. Intercom is not sending webhooks that reach you. Reply on a conversation that is already linked to an issue, then read Has Intercom reached us? on the Jira settings screen. What it says tells you which of the three causes it is:
Pressing Send a test request in Intercom is not a substitute for this. It is inconclusive: nothing syncs from it, and an unchanged screen afterwards tells you nothing either way.
The status message has not changed since I set things up. The app keeps only the most recent notification, and it records only the ones it can act on. An unchanged message therefore means nothing is arriving that this app recognises — not that notifications are being dropped silently. Prove the path with a real reply on a linked conversation, as above.
An attachment visible in Intercom never appears on the issue. Look at the panel's status line. This release prints one of two lines, and neither of them names the reason a file was skipped.
To tell the two skip reasons apart, compare the file with the issue. If an attachment with the same name and size is already there, it was skipped as a duplicate. Otherwise it exceeds your Jira site's attachment limit — Settings → Issues → Attachments — so either raise the limit or accept that the file cannot be synced.
Failures are retried automatically, but errors that cannot succeed on retry — a file over the site limit, an expired token, a deleted issue — stop after the first attempt rather than looping.
The Client secret field has disappeared. It is shown once a token is stored. If the section is gone entirely, no token is stored — go back to step 3.
The connection says the saved token is no longer valid.
🔴 Check the Intercom permissions before you touch the token. The settings screen re-checks
the connection on every load, and that check needs Read one admin as well as
read_conversations. If someone narrowed the Intercom app's permissions after you connected,
a perfectly good token produces this message. Switch Read one admin back on and reload the
screen — nothing else is needed.
Only if both permissions are already on is the token genuinely gone: click Disconnect, then
connect again with a fresh token. Note that disconnecting clears the signing secret too, so
redo step 4 afterwards.
Everything looks configured but large files fail. Your Jira site's attachment limit is almost certainly below the file size. Jira Settings → Issues → Attachments.
Click Disconnect on the settings screen to delete the stored access token and signing secret immediately. Do this before uninstalling if you want the credentials gone at a specific moment — uninstalling leaves cleanup to the Atlassian platform's own schedule.
Attachments that were already synced stay on their Jira issues as ordinary attachments.
Disconnect clears the credentials only. The link between an issue and a conversation, and the sync record for that issue — which includes the file names — are removed by clicking Unlink on that issue's panel. Unlink is the only control that erases the app's own record. A linked issue cannot be pointed at a different conversation without unlinking it first, so there is no second route to check. This is the route to use for a data subject erasure request that touches the app's own records; see the privacy policy §7.
Unlink before you delete the issue. The record is stored under the issue key, and the issue panel is the only place Unlink exists. If the Jira issue is deleted first, the record is left behind and can no longer be reached from the panel. What happens to it after you uninstall follows the Atlassian Forge platform's own data lifecycle — the app performs no deletion of its own on uninstall, and we do not control that schedule. We have no route to such a record either, so we cannot remove one on request — write to support@conduitworks.dev if you need to discuss what remains.