Storage usage & cleanup
Your plan includes a total storage budget for uploaded files. Once the sum of all your attachments reaches the limit, the API blocks further uploads — whether from the widget or the dashboard.
View Current Usage
Analytics → Usage → Card „Storage".
You see three values there:
- Live usage in the smallest meaningful unit (
430 KB,0.43 MB,1.2 GB). Byte-precise from the database — no outdated cache values. - Plan limit in MB (
up to 1,000 MB). Unlimited is shown as∞. - Number of files as subtitle.
Cleanup Button
As soon as at least one file exists, a „Cleanup"-button appears on the card. It removes file attachments from closed conversations — active conversations are always protected.
In the confirmation dialog, you choose how old a conversation must be at minimum:
| Option | Effect |
|---|---|
| Closed for > 30 days | Default. Mirrors the nightly cleanup job. |
| Closed for > 7 days | Faster, still a safety buffer for „accidentally closed". |
| All closed conversations | Cleans up everything that is not active immediately. Practical if you have just closed conversations intentionally and want to reclaim storage. |
After clicking, you see a toast message indicating how many files were removed and how many MB were freed.
What is not cleaned up
- Files from active conversations — they are taboo, even with the most aggressive option.
- Individual files can be selectively removed under Conversations → [Conversation] → Attachments → Delete.
What happens when the limit is reached?
As long as your storage is below the plan limit, uploads are free. When the limit is reached or exceeded:
- The next upload is rejected with
ERR_PLAN_LIMIT_REACHED— both from the widget (visitor upload) and from the dashboard (agent upload). - You can still see the usage on Analytics → Usage and either clean up or upgrade the plan.
Automatic Cleanup in the Background
In addition to the manual button, a cron job runs every night that removes file attachments from conversations that have been closed for more than 30 days. This logic is identical to the default option in the cleanup dialog.
Per-File Size vs. Storage Budget
Note the difference to the file upload settings (see Chat Widget → File Uploads in Chat):
- Per-file size limit (e.g., 2 MB) applies to a single file. Checked before the upload.
- Storage budget (plan limit) applies to the sum of all files of the tenant. Compared against the running sum.
Both are enforced independently of each other.