Overview
The Media Library is fed in two complementary ways, and both reuse the same file that already exists on the platform — nothing is copied and no extra storage is consumed:
- Automatic capture: silently saves the new media that comes in (or goes out) on conversations, as it happens. You don't have to do anything — the file lands in the library already organized.
- Import / backfill: brings into the library the media that already exists in older conversations, in the CRM, in tasks and in the catalog. It's the "sweep of the past": it populates the library in one pass with everything the account has accumulated.
In short: capture handles what's new, import handles what already exists. Both point to the same original file, so nothing is re-downloaded and storage does not grow because of them.
Prerequisites
- The Media Library module enabled for your account (an optional, flag-controlled feature). If you can't find the Library in the navigation, talk to an administrator.
- Reading the capture, import and retention settings is allowed for agents.
- Changing those settings and triggering the import (a heavy operation) are restricted to administrators.
- The account's storage limit is set by the platform operator.
Step by step
Automatic capture
- By default, capture is on for every connection: any new media from conversations is saved to the library automatically, with no manual selection.
- If you prefer finer control, an administrator can turn off the global capture and pick specific inboxes (opt-in per inbox): only the selected connections will then capture.
- Captured files are organized into folders by source, following the inbox → contact → conversation hierarchy, so you can find them by context.
- Capture is deduplicated: the same file (same content) is not saved twice — if the message is re-sent or reprocessed, the library ignores the repeat.
Import / backfill
- On an account that has been in use for a while, an administrator can trigger the import of older media with a single click (an administrator action) to populate the library in one pass.
- The import sweeps the media that already exists in conversations, CRM, tasks and catalog and registers it in the library, reusing the original file (no new upload, no extra storage).
- The operation is idempotent: running it again does not duplicate anything — items already present are simply skipped.
- Beyond the one-time import, there is an incremental sweep that runs periodically and looks at only the new items since the last pass, keeping the library up to date cheaply.
Settings & options
- Capture for all connections vs. inbox list: on for everything by default; an administrator can turn it off and define the list of inboxes that should capture (opt-in per inbox).
- Automatic trash cleanup (
auto_purge_trash_days): items in the trash are permanently removed after a configurable period — default of 30 days. Cleanup uses the same durable flow as a manual deletion: it completes only after storage confirms and preserves history with placeholders. If the same file still has an active alias or one inside its own retention window, cleanup defers that blob instead of deleting the alias early. - One-time retroactive reorganization: on the first sweep, older files that were sitting loose are re-filed into the new folder hierarchy exactly once, without repeating the process afterwards.
Use cases
- An operation that wants every customer file saved automatically, without relying on the team to remember to store each piece of media.
- An old, history-heavy account that needs to populate the library all at once with everything that has flowed through conversations, CRM, tasks and catalog.
- Restricting capture to the official connections only (opt-in per inbox), leaving test inboxes out.
Tips, limits & best practices
- Capture runs off the critical path (asynchronously): it does not delay sending or receiving messages; the file appears in the library right afterwards.
- The storage quota is set by the platform operator — keep an eye on the meter and archive what you no longer use.
- A full import of a large account is heavy; prefer to trigger it at a quiet time so it doesn't compete with peak support hours.
- Since capture and import reuse the same file, it's normal for storage not to grow when you reuse media that was already on the account.
Troubleshooting
- Capture isn't showing up: confirm whether global capture is on or whether that inbox is in the opt-in list; connections outside the selection don't capture.
- The import took a while: it is asynchronous and runs in the background — on large accounts it takes a few minutes; items appear in the library gradually.
- Storage didn't grow after importing: that's expected — the import reuses the original file, so there's no duplication and no storage increase.
- I ran the import twice: that's fine — the operation is idempotent and does not duplicate items already imported.