---
name: kimaai_chatbot_ai_payload
type: filter
since: 1.3.5
tier: free
feature: chatbot
area: chatbot
summary: Changes the request the chatbot sends to the AI provider.
parameters:
  - name: ai_payload
    type: array
    description: The request to the provider, with prompt, postId, postSection, sessionId, lang, aiProvider, aiModel, maxOutputTokens, chatbot_settings, rendersSources and scope, and where they apply temperature or reasoning, the tools, assistantSurface and kbContext.
  - name: payload
    type: array
    description: The normalised request payload, with prompt, postId, postSection, lang, sessionId and chatbot_settings, and assistantSurface in a search answer.
  - name: chatbot_settings
    type: array
    description: The chatbot settings.
returns:
  type: array
  description: The request to send.
surfaces: [chatbot, search]
---

# kimaai_chatbot_ai_payload

## When it fires

Once per chatbot request or search answer, when every check has passed (gate, daily limit, message length) and the tools for the visitor are resolved, right before `kimaai_chatbot_before_request`. The same request goes to the provider whether the answer streams or not.

The keys are KimaAI's own, not the provider's: `aiModel`, `maxOutputTokens`, `temperature`, `tools` and so on are turned into the provider's request later, together with the instructions and the chat history. `aiProvider` is the id of an AI environment of the settings, not a provider name. A search answer carries `assistantSurface` `search` and the search results as `kbContext`. A quick action that forces a tool sets `toolChoice` after this filter.

## Example

```php
add_filter(
  'kimaai_chatbot_ai_payload',
  function (array $ai_payload, array $payload, array $chatbot_settings): array {
    // The answer above the search results stays short.
    if (($payload['assistantSurface'] ?? '') === 'search') {
      $ai_payload['maxOutputTokens'] = min((int) $ai_payload['maxOutputTokens'], 300);
    }

    return $ai_payload;
  },
  10,
  3
);
```

## Related

- `kimaai_chatbot_before_request`: fires with the filtered request.
- `kimaai_chatbot_instructions`: changes the instructions the provider gets.
- `kimaai_chatbot_prompt`: changes only the visitor's message.
