---
# Copy this file to docs/hooks/<name>.md and replace every value. Keep the keys in this order; drop the
# optional ones (returns for actions, surfaces, deprecated) when they do not apply. The check
# (scripts/check-hooks.mjs) compares the page with the hook's docblock and its call sites.
name: kimaai_example_filter # the hook's name, equal to the file name (a browser event: kimaai:chatbot in kimaai-chatbot.md)
type: filter # filter | action | js-filter | js-action | js-event
since: next # the first release with the hook, as in @since; "next" until the release that ships it
tier: free # free | premium (premium when every call site is in premium/)
feature: chatbot # an id of app/Features/Features.php, or "none" for plugin-wide hooks
area: chatbot # chatbot | embedding-search | leads-customer-centre | admin-assistant | settings-admin | tools-addons
summary: Changes the example value before the chatbot uses it. # one sentence, for the index
parameters: # in call order, as the docblock's @param list (name without $, type as in the docblock); [] for none
  - name: value
    type: string
    description: The value to filter.
  - name: payload
    type: array
    description: The normalised request payload.
returns: # filters only, as the docblock's @return
  type: string
  description: The value to use.
surfaces: [chatbot, search] # optional: where it fires, of chatbot | admin_assistant | search
deprecated: # optional; until the release: since "next" and no removal
  since: 1.6.0
  replacement: kimaai_example_replacement
  removal: 1.8.0
---

# kimaai_example_filter

## When it fires

Say which request or job the hook belongs to, on which surfaces it fires (`$payload['assistantSurface']` tells them apart), what has run before it and what a callback can and cannot change. Do not repeat the parameters: the website renders them from the frontmatter.

## Example

```php
add_filter(
  'kimaai_example_filter',
  function (string $value, array $payload): string {
    return trim($value);
  },
  10,
  2
);
```

The block above is the first thing in this section: one fenced `php` block (`js` for a JS hook or a browser event), complete and runnable on its own, without the opening `<?php` tag. The hook's test runs it (`HookPage::example('<name>')`), so it shows the hook's main use. Text that explains it follows the block.

## More examples

Optional: further uses, each with a sentence and a code block.

## Related

- `kimaai_example_action`: what it adds to this hook.
