> ## 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.

# Session retention

> Erase sessions automatically a set number of days after they close or go quiet. Use it when a contract or privacy policy limits how long you keep sessions.

Session retention erases sessions on its own once they're old enough. You pick how many days after a session closes, or after its last message, its content goes. The session record stays, so reports and billing still add up, but what was said, sent and recorded is gone.

Turn it on when a contract or a policy (GDPR storage limitation, HIPAA, your own retention schedule) says you can't keep sessions past a certain age.

> [!NOTE]
>
> **Settings → Security → Session retention**. Viewing it needs the **Session retention** permission
> (Read), and changing it needs **Session retention** (Write). Roles that can change all settings
> already have it.

> [!WARNING]
>
> Erasure is permanent and can't be undone. Both rules are off until you turn them on.

## Turn on session retention

**1. Open the setting**

Go to [**Settings → Security**](https://platform.open.cx/settings/security) and find **Session
retention**.

**2. Turn on a rule**

Turn on **After closing**, **After inactivity**, or both. Each rule starts at 90 days.

**3. Set the threshold**

Enter the number of days for each rule you turned on: a whole number from 15 to 120.

**4. Choose what else to erase**

Turn on the optional erasures your policy needs. See
[Choose what else is erased](#choose-what-else-is-erased).

**5. Save and confirm**

Save your changes. Turning a rule on, or lowering a threshold, asks you to confirm first.

Erasure starts as soon as you confirm. Sessions already past the threshold start being erased within about 30 minutes, and a large backlog can take longer to finish. After that, each session is erased within about 30 minutes of crossing its threshold. If part of an erasure fails, the rest still goes ahead, and the failed part is tried again every 30 minutes until it succeeds.

Turning a rule off, or raising its threshold, applies right away to every session that hasn't been erased yet. Sessions already erased stay erased.

## How the two rules work

| Rule | Erases a session | Applies to |
| - | - | - |
| **After closing** | The set number of days after it was closed | Closed sessions only. A reopened session stops matching, and its count starts over when it closes again. |
| **After inactivity** | The set number of days after its last message, or after it was created if it has none | Every session, open or closed. An open session is closed as resolved first. |

The last message is the latest one from the customer, the AI, your team, a workflow or a sequence. Internal notes and system events, such as a status change or a new tag, don't count.

Some sessions have no recorded close time, such as sessions imported already closed from another tool. **After closing** never matches them; only **After inactivity** does.

With both rules on, whichever comes first erases the session. Say Noor at Payla sets **After closing** to 30 days and **After inactivity** to 90. Riley's session about order #4521, closed on 1 March, is erased at the end of the month. A session Riley started and then abandoned, which nobody closed, is closed and erased 90 days after its last message.

Each rule has one threshold for every channel: web chat, email, phone and messaging. There are no exemptions: every session a rule matches is erased, whatever its tags, team or channel. To keep sessions for a legal hold or a dispute, turn retention off until the hold ends. For rules per channel or per tag, use a [workflow](https://docs.open.cx/security/data-retention.md#trigger-based-removal) instead.

### When the inactivity rule closes a session

An open session that reaches the inactivity threshold is closed as resolved, then erased. Reports count it as a resolved session. Billing follows the same rules as any other close, so a session the AI was handling can count as an AI resolution. See [Billing](https://docs.open.cx/billing.md).

This close doesn't run workflows, doesn't send a CSAT survey, and doesn't update a linked ticket in your help desk.

## What an erasure removes

Every erasure removes:

* **Messages and internal notes.** Their content becomes `[REDACTED]`, including translations and the originals kept when [PII redaction](https://docs.open.cx/safety/pii-redaction.md) is set to **Save the original messages**.
* **Files.** Files customers uploaded and attachments your team sent are removed from storage.
* **Calls.** Call recordings, voicemail audio, and the call details a connected phone system sends.
* **Email copies.** The original email source, and saved copies of outgoing emails.
* **Previews.** The last-message preview in session lists, and notification previews.
* **Other session text.** Saved **Session notes**, CSAT comments, app review text and handoff summaries.
* **Derived content.** The AI's debug data on each message, Voice of Customer transcripts, analyses and examples, what suggested macros learned from the session, the context passed on when an AI call is handed to a person, the page details the web widget sends with each message, copies kept to retry deliveries to a connected help desk, and the session's copies in search and reporting.

### Choose what else is erased

These are off by default. With a switch off, that data stays on the erased session.

| Setting | When on, an erasure also | Default |
| - | - | - |
| **Erase title** | Replaces the session title with `[REDACTED]` | Off |
| **Erase custom data** | Empties the session's custom data, including keys that integrations store there and the attributes your team entered | Off |
| **Erase AI traces** | Removes the AI's working record: each turn, the tools it called with their inputs and results, its reasoning for contact reasons, and its handoff explanations | Off |
| **Erase summary** | Clears the session summary, including the copy a Genesys Cloud connection keeps | Off |
| **Anonymize contact** | Removes everything that ties the session to a person. See [Anonymize the contact](#anonymize-the-contact) | Off |

With all five off, an erased session keeps its title, custom data, AI traces, summary and contact. If your policy says "erase everything", turn them on.

### What stays

The session record: its dates, channel, status, assignee, tags and CSAT score. That's what keeps reports and billing correct after the content is gone.

## Anonymize the contact

With **Anonymize contact** on, an erasure removes every contact identifier from the session, its messages, its CSAT response and its calls: the link to the contact, email addresses, phone numbers, the IP address, the name and avatar on each message, and email sender and recipient addresses. It also removes the session's links to tickets and threads in other tools, such as a Zendesk ticket or a Slack thread, because those identify the person too. The few records that stop a connected tool from importing the same conversation again are kept, with their contact details removed.

The contact record itself is kept, along with the contact's other sessions. To remove it, [delete the contact](https://docs.open.cx/api-reference/contacts/delete.md).

From the moment of erasure, an anonymized session counts as having no contact, so past numbers shift:

* Unique-contact counts drop, and sessions per contact go up.
* The contact's session count, last-contacted date, segments and company metrics no longer include the session.
* Campaign unique contacts and a sequence's reply sessions lose it.
* Filtering the inbox or Voice of Customer by contact no longer finds it.

Billing doesn't count contacts, so it doesn't change.

## What your team and customers see

* **In the inbox,** an erased session stays in your session lists, and its messages read `[REDACTED]`. Its timeline shows **Session content erased due to retention threshold**. Hover over it for the reason, such as *Closed for 30 days* or *No activity for 90 days*.
* **Erased sessions are closed for good.** Replying to one or reopening it, from the inbox or the API, fails with an error, and a status change from a connected help desk doesn't reopen it.
* **Customers** never see the erasure event. If a customer writes again in the same thread, OpenCX starts a new session. The new session links back to the erased one only when the contact wasn't anonymized, because the link itself would show whose session it was. For email, this happens whether or not the [email reply cutoff](https://docs.open.cx/email/forwarding-rules.md#start-a-new-session-for-late-replies) is on.

## Permissions and the audit log

The **Session retention** permission sits under **Settings** in **Settings → Roles**. Read lets a role view the rules; Write lets it change them. Roles with **Settings** (Write) include it, so anyone who can change all settings can turn on erasure. Check who holds that before you rely on the setting. See the [permissions reference](https://docs.open.cx/security/permissions-reference.md).

Every change to the setting is recorded in the [audit log](https://docs.open.cx/security/audit-logs.md), with who made it and each changed value before and after.

## Manage it over the API or MCP

* [Get settings](https://docs.open.cx/api-reference/session-retention/get-settings.md): `GET /session-retention/settings`, with the `session-retention:read` scope.
* [Update settings](https://docs.open.cx/api-reference/session-retention/update-settings.md): `PUT /session-retention/settings`, with the `session-retention:write` scope. Send only the fields you want to change.

A full-access API key can call both. A key limited to chosen scopes needs these scopes added to it.

The [MCP server](https://docs.open.cx/mcp/tools.md) has the same pair: `get_session_retention_settings` and `update_session_retention_settings`. An AI client with write access can turn on erasure, so give `session-retention:write`, or a full-access key, only where you mean to.

Session responses include `erased_due_to_retention_threshold_at`, the time retention erased the session, or `null`. In a session's [history](https://docs.open.cx/api-reference/chat-sessions/list_history.md#retention-erasures), the erasure appears as a `session_erased_by_system_due_to_retention_threshold` event with an optional `reason`, such as `Closed for 30 days`.

## Important notes

> [accordion] Erasure is permanent
>
> Erased content can't be restored from the dashboard or the API. Turning retention off later
> doesn't bring anything back.

> [accordion] Backups and reporting copies
>
> Recovery backups aren't edited one record at a time. They age out on their own schedule.
> Earlier copies in the reporting store are removed as the store merges its data files. See
> [Data retention](https://docs.open.cx/security/data-retention.md#disposal-methods).

> [accordion] Connected tools keep their own copy
>
> Retention erases what OpenCX stores. A help desk or CRM you've connected, such as Zendesk,
> Intercom or HubSpot, keeps its own copy of the ticket or conversation. Set the same retention
> there, or erase it there too. Otherwise, when a contact writes again on a thread whose session
> was anonymized, OpenCX starts a new session, and an integration that brings in the thread's
> earlier messages can copy them back from that tool. The same goes for a historical import you
> run again: it brings back whatever the tool still has, so erase those tickets there, or leave
> them out, before re-importing.

> [accordion] Manual redaction is unchanged
>
> [Redact session](https://docs.open.cx/api-reference/redaction/redact-session.md) and **Redact Message** work as before,
> and redacting an open session by hand still leaves it open. A session you redacted by hand is
> still erased by retention when it passes a threshold, so anything manual redaction left behind
> goes too.

***

## Related Documentation

> [card] [Data retention](https://docs.open.cx/security/data-retention.md)
>
> How long OpenCX keeps each kind of data.

> [card] [PII redaction](https://docs.open.cx/safety/pii-redaction.md)
>
> Strip sensitive values as messages arrive.

> [card] [Redaction API](https://docs.open.cx/api-reference/redaction/index.md)
>
> Redact one message or session on demand.

> [card] [Audit logs](https://docs.open.cx/security/audit-logs.md)
>
> See who changed the retention rules.


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