kimaai_chatbot_rate_limited Hook #

The kimaai_chatbot_rate_limited action fires when a user hits the chatbot’s daily message limit (rate limit). It’s intended for logging, analytics, alerting, and building your own monitoring around usage limits.

This hook runs immediately before the REST API returns an error response to the frontend.

---

When it fires #

Inside the chatbot request handler, the plugin:

1. determines the user’s IP address
2. counts how many chatbot messages that IP has sent “today”
3. compares it to the configured maxMessages limit
4. if the user is at/over the limit, it fires:

do_action('kimaai_chatbot_rate_limited', $user_ip, $today_message_count, $max_messages, $payload, $chatbot_settings);

…and returns an error response (status 400) to the client.

---

Hook signature #

/**
 * Action fired when a user is rate-limited.
 *
 * @param string $user_ip The user's IP address.
 * @param int $today_message_count Number of messages sent today.
 * @param int $max_messages Maximum allowed messages.
 * @param array $payload Normalized payload.
 * @param array $chatbot_settings The chatbot settings.
 */
do_action('kimaai_chatbot_rate_limited', $user_ip, $today_message_count, $max_messages, $payload, $chatbot_settings);

Parameters #

1) $user_ip (string) #

The detected user IP address (as resolved by the plugin’s Security::getIpAddress()).

2) $today_message_count (int) #

How many chatbot messages have already been sent from this IP address today.

3) $max_messages (int) #

The configured maximum allowed messages per day for that IP (from chatbot settings).

4) $payload (array) #

Normalized request payload, typically including:

• prompt (string)
• postId (int)
• selectedTools (string[])
• sessionId (string)

5) $chatbot_settings (array) #

The chatbot settings array used for this request (contains maxMessages, maxInputLength, model/provider settings, etc.).

---

Basic usage: log rate limit events #

add_action('kimaai_chatbot_rate_limited', function (
  $user_ip,
  $today_message_count,
  $max_messages,
  $payload,
  $chatbot_settings
) {
  error_log(sprintf(
    '[KimaAI Chatbot Rate Limited] IP: %s (%d/%d) session=%s postId=%d',
    $user_ip,
    (int) $today_message_count,
    (int) $max_messages,
    (string) ($payload['sessionId'] ?? ''),
    (int) ($payload['postId'] ?? 0),
  ));
}, 10, 5);

---

Example: send an admin alert when abuse is suspected #

This example emails the admin if the same IP hits the limit repeatedly (using an hourly counter).

add_action('kimaai_chatbot_rate_limited', function ($user_ip) {
  $key = 'kimaai_rate_limited_' . md5($user_ip) . '_' . gmdate('YmdH');
  $count = (int) get_transient($key);
  $count++;
  set_transient($key, $count, HOUR_IN_SECONDS);

  if ($count === 5) {
    wp_mail(
      get_option('admin_email'),
      'KimaAI Chatbot: repeated rate limiting',
      "The following IP was rate-limited 5 times within the last hour:\n\n{$user_ip}"
    );
  }
}, 10, 5);

---

Example: track rate limits in analytics (privacy-aware) #

Rather than storing raw IPs, you can hash them.

add_action('kimaai_chatbot_rate_limited', function (
  $user_ip,
  $today_message_count,
  $max_messages,
  $payload
) {
  $ip_hash = hash('sha256', $user_ip);

  if (function_exists('my_analytics_track')) {
    my_analytics_track('kimaai_chatbot_rate_limited', [
      'ip_hash'  => $ip_hash,
      'count'    => (int) $today_message_count,
      'limit'    => (int) $max_messages,
      'postId'   => (int) ($payload['postId'] ?? 0),
      'sessionId_present' => !empty($payload['sessionId']),
    ]);
  }
}, 10, 5);

---

Example: customize the user-facing message (where to do it) #

This hook is notification-only: it fires after the plugin has decided to rate limit the request, and the response message is already being prepared.

If you want to change the message returned to the user, you would do that where the error message is generated (i.e., via a plugin patch or a dedicated filter if you add one). As the code currently stands, kimaai_chatbot_rate_limited is best used for:

• logging
• telemetry / analytics
• alerting
• abuse monitoring

---

Related hooks #

• kimaai_chatbot_gate — blocks requests early for custom policies (not related to daily message limits)
• kimaai_chatbot_blocked — fires when the gate blocks a request (returns 403)
• kimaai_chatbot_error — fires when an exception occurs during AI request execution

---

Best practices #

• Avoid storing raw IP addresses long-term; prefer hashing or short retention.
• Don’t echo or print output (REST response must remain valid JSON).
• Treat $payload['prompt'] and other fields as untrusted input; sanitize before storing/logging.