kimaai_chatbot_gate Filter #

The kimaai_chatbot_gate filter is the chatbot’s early allow/block gate. It runs after the user prompt has been normalized (via kimaai_chatbot_prompt) and before rate limiting, input-length checks, tool resolution, and any AI provider request.

Use it to implement custom policies such as:

• blocking certain prompts/keywords
• requiring login or specific roles
• restricting the chatbot to specific pages/posts
• geo/IP-based restrictions
• maintenance mode / feature flags
• GDPR/consent enforcement
• custom throttling rules beyond the built-in daily limit

If the gate blocks the request, the plugin returns a 403 response and fires kimaai_chatbot_blocked.

---

When it runs #

In the /kimaai/v1/chatbot request flow:

1. Build $payload (prompt, postId, selected tools…)
2. Apply kimaai_chatbot_prompt
3. Apply kimaai_chatbot_gate ✅ (this filter)
4. If blocked → fire kimaai_chatbot_blocked + return 403
5. If allowed → continue with rate limit, length checks, tools, AI request…

---

Filter signature #

/**
 * Gate: allow/block the request early.
 *
 * Return:
 *   - true to allow
 *   - string to block with that message
 *   - WP_Error to block with its message
 *
 * @param bool|string|WP_Error $allowed true, custom message, or WP_Error.
 * @param array $payload Normalized payload (prompt, post_id, …).
 * @param array $data Raw request data.
 * @param WP_REST_Request $request The REST request object.
 * @since 1.3.0
 */
$allowed = apply_filters('kimaai_chatbot_gate', TRUE, $payload['prompt'], $payload, $data, $request);

Parameters #

1) $allowed (bool|string|WP_Error) #

Initial value is true. Return a non-true value to block.

2) $prompt (string) #

The normalized prompt text after kimaai_chatbot_prompt.

3) $payload (array) #

Normalized payload context (commonly includes prompt, postId, selectedTools, etc.).

4) $data (array) #

Raw JSON body from the request (e.g. message, postId).

5) $request (WP_REST_Request) #

REST request object (headers, route, params).

Return values (how to allow/block) #

Return one of:

• true → allow
• "Some message" (string) → block and show that string to the user
• new WP_Error( ... ) → block and show the error message to the user

Anything that is not exactly true is treated as blocked.

---

What happens when blocked #

If blocked, the plugin:

• resolves the error message (string or WP_Error message)
• fires:

do_action('kimaai_chatbot_blocked', $reason, $payload, $data, $request);

• returns:

{ "error": "reason..." }

with HTTP status 403.

---

Basic example: block empty prompts #

add_filter('kimaai_chatbot_gate', function ($allowed, $prompt) {
  if (trim($prompt) === '') {
    return __('Please enter a message.', 'your-textdomain');
  }
  return true;
}, 10, 2);

---

Example: require login #

add_filter('kimaai_chatbot_gate', function ($allowed) {
  if (!is_user_logged_in()) {
    return __('Please log in to use the chatbot.', 'your-textdomain');
  }
  return true;
}, 10, 1);

---

Example: restrict to specific post IDs / pages #

add_filter('kimaai_chatbot_gate', function ($allowed, $prompt, $payload) {
  $post_id = (int) ($payload['postId'] ?? 0);

  // Allow only on posts/pages 10 and 42.
  $allowed_posts = [10, 42];

  if ($post_id && !in_array($post_id, $allowed_posts, true)) {
    return __('Chatbot is not available on this page.', 'your-textdomain');
  }

  return true;
}, 10, 3);

---

Example: block specific content with WP_Error #

Using WP_Error is handy if you want a stable error code internally.

add_filter('kimaai_chatbot_gate', function ($allowed, $prompt) {
  if (stripos($prompt, 'password') !== false) {
    return new WP_Error(
      'kimaai_blocked_sensitive',
      __('Please don’t share passwords or secrets here.', 'your-textdomain')
    );
  }
  return true;
}, 10, 2);

---

Example: simple IP allowlist (advanced) #

If you maintain your own allowlist, you can block everything else.

add_filter('kimaai_chatbot_gate', function ($allowed, $prompt, $payload, $data, $request) {
  $ip = $_SERVER['REMOTE_ADDR'] ?? '';

  $allow = [
    '203.0.113.10',
    '203.0.113.11',
  ];

  if ($ip && !in_array($ip, $allow, true)) {
    return __('Access denied.', 'your-textdomain');
  }

  return true;
}, 10, 5);

Note: if you want the plugin’s canonical IP logic, implement this in a place where you can call the same IP resolver your plugin uses (e.g., via your own service or helper). Using REMOTE_ADDR directly can be unreliable behind proxies/CDNs.

---

Best practices #

• Keep checks fast—this runs on every chatbot message.
• Avoid echoing/printing output (REST response must remain valid JSON).
• Return true explicitly when allowing.
• Prefer WP_Error if you want structured error codes for internal logging/analytics.
• If you need logging when blocked, use kimaai_chatbot_blocked rather than logging directly in every gate rule.

---

Related hooks #

• kimaai_chatbot_prompt — normalize/redact the prompt before the gate
• kimaai_chatbot_blocked — fires when gate blocks a request (403)
• kimaai_chatbot_rate_limited — daily message limit exceeded (400)
• kimaai_chatbot_before_request — fired right before the AI request is sent