> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge sessions

> Bring related work into one primary session while preserving each source history. Learn merge permissions, permanent closure, and reply behavior.

Merging permanently closes one or more source sessions and attaches them as subsessions of a primary session. Each source keeps its original history. The primary receives an internal merge entry with a link and access to the source history.

<Warning>
  A merge cannot be undone. Source sessions cannot be reopened or replied to. Continue the merged work through the primary session, using its channel and recipients.
</Warning>

## Availability and permissions

Merging requires the `merge-sessions:write` permission and OpenCX as the organization's ticketing system (`open`). It is unavailable when another ticketing system is configured. The merge permission authorizes merging any sessions in the organization, regardless of the merger’s assigned or team session scope.

Any channel can be merged into any other channel. All selected sessions must belong to the same organization. Sessions assigned to AI must first be handed off, unassigned, or assigned to a human. Wait until active calls end before merging.

The same permission authorizes public API and MCP execution. API calls execute directly without a separate acknowledgment field. The MCP tool description instructs the caller to warn the user about the irreversible action before executing it.

## Merge from the inbox

1. Open the session you want to keep as the primary.
2. Open **More options** and choose **Merge sessions into this one**.
3. Review the **Primary session** card. Select **Change primary** to choose a different destination.
4. Under **Source sessions**, search by session number and add one or more sources.
5. Choose a closure status for each source and review the permanent-closure, different-contact, and parent-change warnings.
6. Select **Merge permanently**.

Dashboard merges keep the existing required-field checks for closing open sessions. If a source is missing required structured fields, the merge identifies that session and the fields to fill. No source is closed until the batch passes validation. When an open source closes through the dashboard, its stored structured-field answers are also reflected in its session attributes, just as with a normal closure. The primary’s attributes stay unchanged.

To start from a source instead, open its **More options** menu and select **Merge into another session**. Search for the primary to keep, choose a closure status for the source, review the warnings, and select **Merge permanently**.

Use **Show whole history** on an internal merge entry to read a source in a sheet. Opening the source itself shows its permanent-closure warning and a link to its primary. Source histories, summaries, attachments, and mirrored message bodies retain the source session’s read restrictions. Access to the primary does not grant access to a restricted source.

For integrations, use [Merge sessions](/api-reference/chat-sessions/merge) or the MCP `merge_sessions` tool.

## What changes

For each source, the merger chooses **closed-resolved** or **closed-unresolved**. The source receives the `closed_by_merge` tag, an internal entry linking to the primary, and its new parent relationship.

The primary retains its status, assignee, contact, channel, team, priority, tags, and custom attributes. Contact profiles are never combined. Source messages stay in their original history; they are not interleaved chronologically with the primary's history.

If a source is already an ordinary subsession, merging moves it from its previous parent to the primary. The dashboard warns you about this move. A merge that would create a circular hierarchy is rejected.

## Messages received after merging

When an incoming message is addressed to a specific source session, such as an email reply to its original thread, it is stored in that source without reopening it. The primary receives a top-level internal entry identifying the source session and sender, with the message and a link to its original history. This updates the primary's last-message timestamp without changing its status or assignee.

The internal entry is visible to agents, not to customers; its message body is available only to agents who can read the source. Email replies from people outside the source’s participants remain private notes and are also mirrored, preserving the sender and private-note explanation. They never reopen the source or add recipients. It does not add the source contact to the primary's recipients. When the sessions have different contacts, review the red dashboard warning carefully: a reply from the primary may not reach the source contact.

If a voicemail finishes processing after its source was merged, the recording stays with the source and a single internal entry appears in the final primary. The source stays closed, and the entry provides access to the recording subject to the source’s read permissions.

Mirrored messages can display their saved translation using your translation display preferences. If no saved translation is available, the original is shown.

WhatsApp, Messenger, Instagram, and SMS keep their normal incoming-message routing: reuse an open session for the contact on that channel, or create a new one. Merging does not redirect these incoming messages into the primary. The merged source stays closed, and the new or existing open session can be replied to normally. Quoting an older WhatsApp message does not change this routing.

Redaction preserves merge entries and their source/primary links. Redacted entries hide message content and summaries while keeping the merge trail visible. Redacting a source session also clears its summary; opening a linked source history still requires access to that source.

## Merging a primary later

A session can become a merged source only once, but it can receive multiple sources while it remains a primary.

If B is merged into A and A is later merged into D, the original links and histories remain. New messages received in B stay in B and appear once in D, identified as messages from B. Neither B nor A reopens.

## Workflows, billing, and reporting

Merge closure emits the ordinary closure event after `closed_by_merge` has been saved. Workflows can use **Get Ticket Tags** to check this tag and decide how to handle the closure. The closure event payload does not gain a tags field.

Only a newly completed merge dispatches closure workflows. Retrying an already completed merge does not dispatch them again or recover workflows missed if dispatch was interrupted.

Configured workflow actions may still run, but merged sources cannot be reopened or replied to. Merging does not change billing or transfer or reset SLAs. Use `closed_by_merge` in your reporting to distinguish merged closures from other outcomes.

<Warning>
  Finish pending replies and avoid simultaneous changes to the selected sessions before merging. A merge does not wait for operations already in progress; an in-flight reply or status change may complete after the merge. Concurrent merges or parent changes can interfere with one another.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.