Retention Policy

Retention policy in Rocket.Chat enables you to automatically delete old messages and files in your workspace based on custom rules.

Permissions

Retention policies depend on two types of permissions:

• edit-privileged-setting: It is required to set global policy.

• edit-room-retention-policy: It is required to set per-room policy.

To enable channel owners to set their policies, assign edit-room-retention-policy permission to channel owners. By default, it is assigned to administrators only.

Configuration

To enable retention policy on your workspace,

• Navigate to Administration > Workspace > Settings > Retention Policy.

• Toggle on Enabled.

• Timer Precision: It establishes how often the deletion script should run. When your policies have a long lifetime or are not concerned about precision, you can lower this to save processing power.

• Use Advanced Retention Policy Configuration: If enabled, it uses an advanced retention policy configuration, which provides more granular control of the pruning frequency.

• Use Advanced Retention Policy Cron: Define how often the prune timer should run with a cron job expression. Setting this to a more precise value makes channels with fast retention timers work better, but might cost extra processing power for large communities.

When the "Use Advanced Retention Policy Configuration" setting is enabled, the policy follows the cron job expression set in "Use Advanced Retention Policy Cron". If it's disabled, the policy follows the Timer Precision settings.

There are two levels of retention policies in Rocket.Chat: global policies (enforced across the entire workspace) and per-room policies (implemented in specified rooms).

Global policies

Tweaking these settings without extreme caution can destroy all message history across your server. Please read this entire section before you enable this feature.

To update the Global Policies settings, navigate to Administration > Workspace > Settings > Retention Policy > Global Policies.

The policy is split into three parts: one for all channels, one for all private groups, and one for all direct messages. Each type has two options:

• Prune in channels/private groups/direct messages: Enabling this option applies the global retention policy to this type of message. For example, if you only wish to prune messages in private groups, enable the option for private groups and disable the others.

• Prune messages older than in channels/private groups/direct messages: This option sets the time period (in days, hours, or minutes) for automatically deleting messages. For instance, entering 30 and selecting “days” will delete all messages older than 30 days. Similarly, entering 48 and selecting “hours” or “minutes” will remove messages older than 48 hours or 48 minutes, respectively.

Furthermore, other options allow you to specify how the policy works:

• Do not prune pinned messages: If enabled, pinned messages are not deleted. For example, when you pin a few messages with essential links, these messages stay intact.

• Only delete files: If enabled, messages are not deleted, but files are. They are replaced by a simple “File removed by automatic prune message.” When combined with Do not prune pinned messages, only unpinned files are deleted.

• Do not prune discussion messages: If enabled, discussion messages are not deleted. All the discussions in your workspace remain intact.

• Do not prune Threads: When enabled, threads are not deleted. All the threads in your workspace remain intact.

If you don't enable Do not prune discussion messages, all your discussion messages will be deleted irrespective of the dates.

Per-room policies

Tweaking these settings without extreme caution can destroy all message history across your server. Please read this entire section before you turn the feature on.

Ensure you have the edit-room-retention-policy permission.

To enable an automated retention policy in a room that overrides the global retention policy,

• Click the Room Information icon and select the Edit button.

• Go to Prune.

  • Automatically prune old messages: Enable this option to prune old messages automatically.

  • Override global retention policy: When enabled, you can define a retention policy for the room that overrides the global policy.

  • Maximum message age in days: This option sets the time period (in days) for automatically deleting messages. For instance, entering 30 will delete all messages older than 30 days, while entering 365 will remove messages older than a year.

  • Exclude pinned messages: When enabled, do not prune pinned messages.

  • Prune files only, keep messages: When enabled, remove only files during pruning and keep the messages.

  • Do not prune threads: Messages in threads are not deleted if enabled.

• Click Save.

Users can determine if a room’s messages will be pruned by scrolling to the top of the message history or opening the room info. A warning is displayed if an automated policy (global or per-room) is present. For example, “Messages older than 3 months will be pruned on June 26, 2012 at 11:30 PM” or “Files older than 3 months will be pruned on May 13, 2020 at 11:50 PM”.

You can also manually prune selected messages in a room as needed, outside of the automated retention policies following these steps:

• Navigate to the kebab menu in the room header.

• Click Prune Messages and update the following options:

  • Newer than: Set a date and time to prune messages newer than the selected moment.

  • Older than: Set a date and time to prune messages older than the select moment.

  • Only prune content from these users: Select users to delete their messages. Leave empty to prune everyone's content.

  • Inclusive: If you check the inclusive checkbox, messages sent on and between Newer than and Older than dates are deleted (messages are deleted between and including those dates). If you don't check the inclusive checkbox, messages between Newer than and Older than dates are deleted, and the messages sent on those dates are not deleted.

  • Do not prune pinned messages: Pinned messages are not deleted if enabled. For example, if you pinned a few messages with important links, they stay intact.

  • Do not prune discussion messages: If enabled, messages in the discussions are not deleted.

  • Do not prune threads: If enabled, messages in the threads are not deleted.

  • Only remove the attached files, keep messages: If enabled, messages are not deleted, but files are. They are replaced by a simple File removed by automatic prune message. When used together with Exclude pinned messages, only unpinned files are deleted.

• Click Prune.

The selected messages are deleted immediately based on the specified criteria.