---
name: kimaai_admin_assistant_rate_limited
type: action
since: 1.5.0
tier: free
feature: admin-assistant
area: admin-assistant
summary: Fires when an administrator reaches the admin assistant's daily message limit.
parameters:
  - name: user_id
    type: int
    description: The administrator's user ID.
  - name: today_message_count
    type: int
    description: The administrator's answered messages today, as stored in the assistant's history.
  - name: max_messages
    type: int
    description: The daily limit.
  - name: settings
    type: array
    description: The admin assistant's runtime settings.
surfaces: [admin_assistant]
---

# kimaai_admin_assistant_rate_limited

## When it fires

When an admin assistant request finds today's count of the administrator's answered messages at the daily limit or above it, after the gate and before the maximum message length is checked. The administrator gets an error with status 400 that asks them to try again tomorrow; the action fires before that error is returned, and nothing reaches the AI provider. It fires for every refused message.

The limit is per administrator, not per site. The admin assistant has no daily limit by default: its configuration sets `maxMessages` to 0 and the settings offer no limit, so out of the box this action does not fire.

## Example

```php
add_action(
  'kimaai_admin_assistant_rate_limited',
  function (int $user_id, int $today_message_count, int $max_messages): void {
    // One email per administrator and day.
    $key = 'my_assistant_limit_mail_' . $user_id;
    if (get_transient($key)) {
      return;
    }
    set_transient($key, 1, DAY_IN_SECONDS);

    wp_mail(
      get_option('admin_email'),
      'An administrator reached the assistant limit',
      sprintf('User %d sent %d messages to the admin assistant today, the limit is %d.', $user_id, $today_message_count, $max_messages)
    );
  },
  10,
  3
);
```

## Related

- `kimaai_admin_assistant_blocked`: fires when the gate refuses a message.
- `kimaai_chatbot_rate_limited`: the same action for the chatbot's limit per visitor.
