Message Retention

Your plan defines how long Kirimdev stores message history. Messages older than that window are permanently deleted, together with the media files Kirimdev downloaded on their behalf.

This is not an archive tier or a visibility filter. The rows are removed. There is no endpoint to restore them and upgrading to a longer window does not bring back messages already deleted.

The window

Plan	History retained
Starter	90 days
Pro	365 days
Business	365 days

The authoritative value for your organization is the quota.history_retention_days entitlement. Read it rather than hard-coding a number — plans change, and your account may be on a custom value.

A value of -1 means unlimited: nothing is ever deleted.

What gets deleted

A message becomes eligible once its created_at is older than the window. When it is removed, so is:

• the message record itself, and with it its content, status, timestamps and delivery metadata
• inbound media Kirimdev downloaded from WhatsApp for that message — the file behind media_url stops resolving
• any AI agent run recorded against that message

What survives

Deletion is scoped to messages. It does not cascade upward or sideways:

• Contacts — names, phone numbers, custom fields, labels, notes
• Conversations — the thread itself remains, with its assignment, labels, status and last-activity timestamp. A conversation is one phone number and it stays; only its old messages go.
• Media Library — files you uploaded through the dashboard or API have their own lifecycle and count against your storage quota. They are never removed by retention, even when a message that used them is.
• Broadcast campaigns — campaign records and their per-recipient rows
• Deals, pipelines, contact activity, and every other CRM record

Plan downgrades shorten the window immediately

Moving from a 365-day plan to a 90-day plan means messages between 90 and 365 days old become eligible for deletion at the next nightly sweep. Export anything you need before downgrading.

Effect on the API

GET endpoints that read message history return only what is still stored. A request for a range older than your window comes back empty or partial — this is a successful response, not an error, and it is indistinguishable from a period in which you genuinely sent nothing.

If your integration reconciles against Kirimdev as a source of truth, treat the retention window as the horizon and store anything you need beyond it on your side.

Webhook payloads are unaffected. They are delivered when the event happens, long before any message reaches the window.

Keeping data longer

Retention is not configurable per-request. If you need history beyond your plan’s window:

• Export as you go. Subscribe to message.received and message.sent webhooks and persist what you need in your own system. This is the most reliable approach — you capture the message at the moment it happens rather than racing a deletion.
• Mirror media you care about. media_url points at storage Kirimdev manages and stops resolving once the message is deleted. Download and re-host anything you need to keep.
• Move to a longer plan before the data ages out. Upgrading extends the window from that point forward; it cannot recover what has already gone.

Analytics

Aggregate metrics — message volume, delivery funnel, per-template performance — remain available for periods whose messages have been deleted. Kirimdev captures daily counters before deletion, so charts do not go blank when history ages out.

Metrics that pair two specific messages, such as response times, are the exception. They cannot be reconstructed from counters and are reported only for the period still covered by your retention window.