> ## 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 > Permanently merge source sessions into a primary while keeping original histories separate. Requires merge-sessions:write and OpenCX ticketing. Merging is irreversible. Sources are permanently closed and cannot be reopened or replied to. Continue the merged work through the primary session's channel and recipients, including when contacts differ. Requires `merge-sessions:write`. The organization's ticketing system must be `open`. API callers execute directly; there is no acknowledgment field. Choose `closed_resolved` or `closed_unresolved` for each source. Every source receives `closed_by_merge` and becomes a subsession of the primary. The primary retains its status, assignee, contact, channel, fields, and tags. Internal merge entries link the original histories; messages are not interleaved chronologically. ```json theme={"dark"} { "idempotencyKey": "00000000-0000-4000-8000-000000000001", "sources": [ { "sessionId": "ce38e481-5ea1-46ca-a6d1-ab897b73b53a", "status": "closed_resolved" }, { "sessionId": "8150934d-1812-4481-b17e-15a99fdd433a", "status": "closed_unresolved" } ] } ``` Use a fresh `idempotencyKey` for each merge. If a request times out or its response is lost, retry with the same primary, sources, closure choices, and key. A key reused for a different operation is rejected. Eligibility failures close none of the selected sources. Closure workflows are dispatched only by the request that newly completes the merge. A retry returns the saved merge without dispatching them again. If dispatch is interrupted after the merge is saved, retrying does not recover missed workflows. All sessions must belong to the same organization. Self-merges, repeated sources, circular hierarchies, previously merged sources, AI-owned sessions, and active calls are rejected. A primary that has received sources may later be merged into another primary. Messages addressed to a specific source, such as replies to its original email thread, stay there and mirror internally into the final primary without reopening either session. WhatsApp, Messenger, Instagram, and SMS keep normal routing to an open session or a new session; incoming messages are not redirected by the merge. Redaction preserves merge links while hiding sensitive content. See [Merge sessions](/inbox/merge-sessions) for dashboard warnings, history viewing, and reporting behavior. 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. ## OpenAPI ````yaml post /chat/sessions/{session_id}/merge openapi: 3.1.0 info: title: OpenCX API description: > OpenCX is an AI-powered, all-in-one platform for customer support and outbound communications. Use this API to manage your OpenCX organization's AI agents, actions, conversations, contacts, and more. To get started, generate a new API key from the dashboard. ## Authentication All API endpoints require authentication using a Bearer token. You can generate an API key from your OpenCX dashboard. ## Rate Limiting API requests are rate limited to ensure fair usage. The current limits are: - 100 requests per minute for standard endpoints - 1000 requests per minute for streaming endpoints ## Error Handling The API uses standard HTTP status codes and returns detailed error messages in the response body. version: 1.0-beta license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: http://localhost:8080 description: Development - url: https://api.open.cx description: Production security: - bearerAuth: [] paths: /chat/sessions/{session_id}/merge: post: summary: Merge sessions description: >- Permanently close source sessions and attach them to this primary. Sources cannot be reopened or replied to. All replies use the primary channel and recipients. Requires merge-sessions:write and OpenCX ticketing. Reuse idempotencyKey with the identical request when retrying. operationId: mergeSessions parameters: - schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: session_id required: true requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MergeSessionsInput' responses: '200': description: Default Response content: application/json: schema: $ref: '#/components/schemas/MergeSessionsResult' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorDto' components: schemas: MergeSessionsInput: $schema: https://json-schema.org/draft/2020-12/schema $id: '#/components/schemas/MergeSessionsInputInput' type: object properties: idempotencyKey: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sources: minItems: 1 type: array items: type: object properties: sessionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string enum: - closed_resolved - closed_unresolved required: - sessionId - status required: - sources MergeSessionsResult: $schema: https://json-schema.org/draft/2020-12/schema $id: '#/components/schemas/MergeSessionsResult' type: object properties: mergeId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ primarySessionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sources: type: array items: type: object properties: id: type: string ticket_number: type: number main_status: type: string enum: - closed_resolved - closed_unresolved - open required: - id - ticket_number - main_status additionalProperties: false required: - mergeId - primarySessionId - sources additionalProperties: false ErrorDto: type: object properties: statusCode: type: integer message: type: string error: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.