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 and belong to the tenant.

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 so you can switch between the two.
• 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 remembered per tenant and per user — the browser stores it under the key conversationToolsTab.<tenantId>.<userId> — so switching tenants or signing in as someone else won’t leave you looking at the wrong tab. A remembered 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.

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.