---
name: kimaai_chatbot_gate
type: filter
since: 1.3.5
tier: free
feature: chatbot
area: chatbot
summary: Blocks a visitor's message before anything is sent to the AI provider.
parameters:
  - name: allowed
    type: true|string|WP_Error
    description: True to answer. A message or a WP_Error blocks the request; its message is what the visitor sees.
  - name: prompt
    type: mixed
    description: The visitor's message after kimaai_chatbot_prompt, with card numbers and IBANs masked.
  - name: payload
    type: array
    description: The normalised request payload, with prompt, postId, lang and chatbot_settings; postSection in the chat, assistantSurface in a search answer.
  - name: data
    type: array
    description: The request's JSON body.
  - name: request
    type: WP_REST_Request
    description: The REST request.
returns:
  type: true|string|WP_Error
  description: True to go on; anything else blocks.
surfaces: [chatbot, search]
---

# kimaai_chatbot_gate

## When it fires

In every chatbot request and every search answer, after `kimaai_chatbot_prompt` and the masking, before the daily limit is counted and before the session is opened. KimaAI hooks it itself at priority 10 to refuse the banned words and IP addresses of the chatbot settings, so `$allowed` can already be a message when your callback runs.

Only `true` lets the request go on. A string or a `WP_Error` blocks it: the visitor gets its message with status 403, `kimaai_chatbot_blocked` fires, and nothing reaches the provider. Any other value blocks it with a general message. The filter can only block: return `$allowed` unchanged when it is not `true`, so you never let through what an earlier check refused. In a search answer `$payload['assistantSurface']` is `search`, and a blocked visitor gets no cached answer either.

## Example

```php
add_filter(
  'kimaai_chatbot_gate',
  function ($allowed, $prompt) {
    if ($allowed !== true || !is_string($prompt)) {
      return $allowed;
    }

    // Links in a question are mostly spam.
    if (preg_match('~https?://~i', $prompt)) {
      return __('Please ask your question without links.', 'my-theme');
    }

    return $allowed;
  },
  10,
  2
);
```

## More examples

Members only: the chatbot answers logged-in visitors.

```php
add_filter(
  'kimaai_chatbot_gate',
  function ($allowed) {
    if ($allowed === true && !is_user_logged_in()) {
      return new WP_Error('my_theme_members_only', __('Please log in to use the chat.', 'my-theme'));
    }

    return $allowed;
  }
);
```

## Related

- `kimaai_chatbot_blocked`: fires when the gate blocks a message.
- `kimaai_chatbot_prompt`: changes the message before the gate sees it.
- `kimaai_chatbot_daily_message_limit`: the other limit on a visitor, counted after the gate.
