---
name: kimaai_chatbot_blocked
type: action
since: 1.3.5
tier: free
feature: chatbot
area: chatbot
summary: Fires when the chatbot's gate blocks a visitor's message.
parameters:
  - name: error_message
    type: string
    description: The message the visitor gets.
  - 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.
surfaces: [chatbot, search]
---

# kimaai_chatbot_blocked

## When it fires

Right after `kimaai_chatbot_gate` returned anything but `true`, in a chatbot request or a search answer, before the visitor gets the refusal with status 403. This covers KimaAI's own banned words and banned IP addresses as well as the rules of your gate callbacks. The request ends here: no session is opened, the daily limit does not count it and nothing reaches the AI provider.

The action cannot change the outcome. `$payload['prompt']` holds the blocked message with card numbers and IBANs masked; it can still contain other personal data, so think before you store it.

## Example

```php
add_action(
  'kimaai_chatbot_blocked',
  function (string $error_message, array $payload): void {
    $surface = $payload['assistantSurface'] ?? 'chatbot';
    error_log(sprintf('KimaAI blocked a message (%s): %s', $surface, $error_message));
  },
  10,
  2
);
```

## Related

- `kimaai_chatbot_gate`: decides whether a message is blocked.
- `kimaai_chatbot_rate_limited`: fires when a visitor reaches the daily limit instead.
