---
name: kimaai_chatbot_session_retention_should_run
type: filter
since: 1.4.9
tier: free
feature: chat-history
area: chatbot
summary: Pauses a run of the cleanup that deletes old chatbot conversations.
parameters:
  - name: should_run
    type: bool
    description: Whether the run goes ahead, true.
  - name: context
    type: array
    description: source (schedule or fallback), settings, mode, effectiveDays and cutoffTimestamp, the date and time ("Y-m-d H:i:s", site time zone) before which conversations count as old.
returns:
  type: bool
  description: False skips this run.
---

# kimaai_chatbot_session_retention_should_run

## When it fires

At the start of each run of the conversation cleanup, when "Delete old conversations" is on and the retention period is at least one day. A run starts from the daily schedule (Action Scheduler, else WP-Cron; `source` `schedule`), or on an admin or cron request when the last run was more than a day ago and no scheduled run lies ahead (`source` `fallback`).

Returning `false` skips this run only; nothing is deleted and the next run asks again. A run that goes ahead takes a lock for up to two hours, so two runs never overlap.

## Example

```php
add_filter(
  'kimaai_chatbot_session_retention_should_run',
  function (bool $should_run, array $context): bool {
    // An export of the conversations is running: delete nothing until it is done.
    if (get_transient('my_chat_export_running')) {
      return false;
    }

    return $should_run;
  },
  10,
  2
);
```

## Related

- `kimaai_chatbot_session_retention_days`: the retention period.
- `kimaai_chatbot_session_retention_before_cleanup`: fires when the run goes ahead.
