kimaai_chatbot_gate

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.