How to Link a Conversation to an Issue

A conversation and an Issue are two different records — the conversation is the customer’s thread, the Issue is the tracked problem it’s evidence of. Linking the two lets an agent see, right on the conversation header, whether it’s already tied to something the team is tracking, and lets them attach a conversation to an Issue (or detach it) without leaving the inbox.

This article covers viewing linked Issues, linking and unlinking a conversation from the inbox, and the permission split between looking, linking, and creating a report.

What you need

Your workspace needs the Issues module switched on. On top of that, three different actions on this surface are gated three different ways:

• See a conversation’s linked Issue(s) — issues.view
• Link a conversation to an Issue — issues.manage
• Unlink a conversation from an Issue — issues.manage
• Create a new Issue report from a conversation — Tenant membership only — not gated on issues.manage

Neither the standard agent role nor the reader role holds issues.manage by default — both hold issues.view (and the agent role also holds issues.create), so both can see linked Issues but neither can attach or detach one. If you don’t have it, the link and unlink controls — including the link button inside the empty state — simply aren’t offered; nothing you see will send you into a permission error. Reporting a new Issue is deliberately left open: it opens the Create Issue pane and posts to /api/issue-reports, a route that only checks that you’re signed in, belong to the tenant, and have the Issues module switched on.

Without the Issues module or without issues.view, the linked-Issue read never runs at all: no pills appear on the header, and the panel has no Issues surface.

Viewing an Issue linked to a conversation

Open any conversation in the inbox. If it’s linked to one or more Issues, you’ll see a status-colored pill on the conversation header for each linked Issue, showing #<number> and the Issue’s title. The pill’s color comes from the Issue’s status in your tenant’s own status vocabulary, not a fixed table, so it always matches the colors your team sees elsewhere for that status. A status your team has since deleted falls back to a neutral tint rather than borrowing another status’s color.

The header shows at most two pills — a fixed cap, not a measured fit. If the conversation is linked to more than two Issues, a +N pill follows them with the count of the rest.

The two kinds of pill go to two different places:

• Clicking a status pill opens that Issue in the Issue Tracker (/issues/<number>).
• Clicking the +N pill opens the side panel on its Issues tab, which lists them all.

If the linked-Issue read fails, the header shows nothing at all rather than an empty row — an absent adornment makes no claim, where an empty-looking one would wrongly say “no issues.”

In Monitor, which renders a conversation without a side panel, the pills still show but render as plain, non-clickable text rather than buttons — a button that looks pressable with nowhere to go is worse than static text.

Opening the Cases & Issues panel

With a conversation open, press K (or use the panel dock) to toggle the side panel. What it’s called and what it shows depends on which modules your tenant has enabled:

• Both Cases and Issues enabled: the panel is labeled Cases & Issues and shows a tab bar — All, Cases and Issues — and opens on All, which lists both together.
• Only one enabled: the panel is labeled Cases or Issues, whichever one you have, with no tab bar — a switcher with one option decides nothing.
• Neither enabled: K does nothing, and the dock button and command-palette entry both drop out.

Note that K here is the bare letter. Cmd/Ctrl + K is the global command palette, which is a different shortcut.

Which tab you’re on is kept only while the panel stays open on this conversation — closing the panel or moving to another conversation puts it back on its default view. A chosen tab is never trusted on its own: if the module behind it has since been switched off, the panel opens on the one you still have. Clicking the +N pill always takes you to the Issues tab specifically, even if the panel is already open on Cases.

Linking a conversation to an Issue

1. Open the conversation you want to link.
2. Open the Cases & Issues panel (K) and switch to the Issues tab if you’re not already on it.
3. Click the link icon in the panel header (Link existing issue), or the Link existing issue button in the empty state if the conversation has no Issues yet.
4. In the Link an issue picker, search by title (Search issues by title…) and narrow by state with the Open / Closed / All tabs — Open is the default. Long result lists page with Load more.
5. Click the Issue you want. That links it immediately — there’s no separate confirm step. A linked row shows a tick; clicking a ticked row unlinks it again.

The search runs on the server, so it covers the whole tracker rather than only the results already on screen.

Both the link icon and the empty state’s link button only appear if you hold issues.manage. Once linked, the Issue’s status pill appears on the conversation header immediately, and the panel reflects the new link without needing a manual refresh.

Unlinking a conversation from an Issue

From the Issues tab, each linked Issue row carries an X button (Unlink from this conversation) that only appears if you hold issues.manage. You can also unlink from the Link an issue picker by clicking an Issue that’s already ticked. You cannot unlink from a header pill — clicking a status pill opens the Issue instead.

One case is refused on purpose: you cannot unlink the conversation the Issue was originally reported from. That thread is the reporter’s own conversation, and unlinking it would orphan it — the reporter’s next reply would silently open a second conversation instead of continuing the one your team already has history in. The server rejects it with:

This conversation is where the issue was reported. It cannot be unlinked.

In the inbox the refusal surfaces as a Could not unlink the issue notification and the row reappears in the panel; it never silently succeeds. This restriction only applies to the reporter’s own conversation — the one carrying the reporter’s contact. Any other conversation an agent has linked to that Issue can be unlinked normally.

Seeing and unlinking from the Issue page

The link works from both ends. Open an Issue in the Issue Tracker and, when at least one conversation is linked, its detail page carries a Conversations section listing every conversation linked to it — each one’s subject, the customer it’s with, its channel, and when it was linked — with an Open link that opens the thread in the inbox in a new browser tab. Anyone who can view the Issue sees this list; reading it doesn’t need manage rights.

If you hold issues.manage, each conversation that can be detached carries an Unlink button. The one conversation the Issue was originally reported from is kept: in place of an Unlink it shows a short Reporter’s conversation note, for the same reason the inbox refuses that cut — unlinking it would orphan the reporter’s thread. Every other linked conversation can be unlinked here, and an Issue is allowed to end up with no linked conversation at all.

So a conversation can be attached or detached from either side — the conversation’s Cases & Issues panel, or the Issue’s own Conversations section — and the two stay in step.

Creating a new Issue instead of linking to an existing one

If the conversation doesn’t match anything already tracked, use the panel’s Create issue action — the + button in the panel header, or the Create issue button in the empty state. This opens the Create Issue pane already bound to this conversation and submits to /api/issue-reports — it doesn’t require issues.manage, so it’s available to anyone who can see the panel, not just agents who can manage links. The empty state also offers Open the Issue Tracker if you’d rather work in the module itself.

See Report an Issue from a Conversation for the full reporting flow, including the Shift+I shortcut and the wrap-up macro.

Notes

• The panel’s internal id is cases regardless of what label it’s showing (Cases, Issues, or Cases & Issues) — this only matters if you’re troubleshooting the dock or a “last panel” restore that seems to disagree with the label on screen.
• Linked-Issue data on the header and in the panel is treated as stale after 15 seconds and re-read when the browser tab regains focus, so another agent’s link, unlink, or status change lands without reopening the conversation.