---
name: kimaai_chatbot_rate_limited
type: action
since: 1.3.5
tier: free
feature: chatbot
area: chatbot
summary: Fires when a visitor reaches the chatbot's daily message limit.
parameters:
  - name: user_ip
    type: string
    description: The visitor's IP address, as KimaAI resolves it (see kimaai_trusted_proxies).
  - name: today_message_count
    type: int
    description: The answered messages from this address today.
  - name: max_messages
    type: int
    description: The daily limit, after kimaai_chatbot_daily_message_limit.
  - name: payload
    type: array
    description: The normalised request payload, with prompt, postId, postSection, lang, sessionId and chatbot_settings, and assistantSurface in a search answer.
  - name: chatbot_settings
    type: array
    description: The chatbot settings.
surfaces: [chatbot, search]
---

# kimaai_chatbot_rate_limited

## When it fires

When a chatbot request or a search answer finds today's count of answered messages from the visitor's address at the daily limit or above it. The visitor gets an error with status 400 that asks them to come back tomorrow; the action fires before that error is returned, and nothing reaches the AI provider.

It fires for every refused message, so a visitor who keeps trying fires it again and again. The IP address is personal data: keep it out of emails and logs you do not need it in.

## Example

```php
add_action(
  'kimaai_chatbot_rate_limited',
  function (string $user_ip, int $today_message_count, int $max_messages): void {
    // One email a day is enough.
    if (get_transient('my_chatbot_limit_mail')) {
      return;
    }
    set_transient('my_chatbot_limit_mail', 1, DAY_IN_SECONDS);

    wp_mail(
      get_option('admin_email'),
      'A visitor reached the chatbot limit',
      sprintf('A visitor sent %d messages today and reached the limit of %d.', $today_message_count, $max_messages)
    );
  },
  10,
  3
);
```

## Related

- `kimaai_chatbot_daily_message_limit`: sets the limit.
- `kimaai_chatbot_blocked`: fires when the gate refuses a message.
