kimaai_chatbot_ai_payload

Table Of Contents

kimaai_chatbot_ai_payload Filter #

The kimaai_chatbot_ai_payload filter lets you finalize and modify the AI provider request payload right before it’s sent to AiService::run().

Use it to:

  • add or adjust system/context fields (if your AiService supports them)
  • inject metadata (site name, user role, locale, page context)
  • override model/provider settings dynamically
  • enforce tool behavior (toolChoice, disable tools, etc.)
  • add custom headers/parameters (provider-specific) if supported downstream

When it runs #

In the /kimaai/v1/chatbot request flow, the plugin:

  1. builds $ai_payload from normalized payload + chatbot settings
  2. optionally attaches tools, toolChoice, parallelToolCalls
  3. applies this filter:
$ai_payload = apply_filters('kimaai_chatbot_ai_payload', $ai_payload, $payload, $chatbot_settings);
  1. fires kimaai_chatbot_before_request
  2. calls:
$response = $this->ai_service->run($ai_payload, 'chat');

This filter is your last chance to change what is sent to the AI provider.

Filter signature #

/**
 * Filter: finalize the AI request payload (headers, system prompt, metadata, etc.).
 *
 * @param array $ai_payload Provider-specific request body.
 * @param array $payload Normalized payload.
 * @param array $chatbot_settings Settings array.
 * @return array
 */
$ai_payload = apply_filters('kimaai_chatbot_ai_payload', $ai_payload, $payload, $chatbot_settings);

Parameters #

1) $ai_payload (array) #

The provider request body being assembled. Typically includes:

  • prompt (string)
  • postId (int)
  • sessionId (string)
  • aiProvider (string)
  • aiModel (string)
  • temperature (float/int)
  • maxOutputTokens (int)

Optional tool-related keys (present only when tools are enabled and selected):

  • tools (array)
  • toolChoice (string|array) — e.g. "auto", "none", or ['type'=>'function','name'=>'...']
  • parallelToolCalls (bool)

Note: Some keys may be transformed (e.g., snake_cased) by AiService before being sent to OpenAI-compatible APIs.

2) $payload (array) #

Normalized request context:

  • prompt, postId, sessionId, selectedTools
  • and any other internal context added earlier in the flow

3) $chatbot_settings (array) #

Chatbot settings for this request (model/provider, limits, temperature, etc.).

Return value #

Return the modified $ai_payload array.

Basic example: force a specific model for admins #

add_filter('kimaai_chatbot_ai_payload', function (array $ai_payload): array {
  if (is_user_logged_in() && current_user_can('manage_options')) {
    $ai_payload['aiModel'] = 'gpt-4.1'; // example model name
  }
  return $ai_payload;
}, 10, 1);

Example: add lightweight page context to the prompt #

If you want the AI to be page-aware without changing your frontend, prepend context here.

add_filter('kimaai_chatbot_ai_payload', function (array $ai_payload): array {
  $post_id = (int) ($ai_payload['postId'] ?? 0);
  if ($post_id <= 0) {
    return $ai_payload;
  }

  $title = get_the_title($post_id);
  if (!$title) {
    return $ai_payload;
  }

  $ai_payload['prompt'] = "Context: You are assisting a visitor on the page titled \"{$title}\".\n\nUser: " . $ai_payload['prompt'];

  return $ai_payload;
}, 10, 1);

Example: disable all tools for certain pages #

add_filter('kimaai_chatbot_ai_payload', function (array $ai_payload): array {
  $post_id = (int) ($ai_payload['postId'] ?? 0);

  // Example: disable tools on checkout page.
  if ($post_id === 1234) {
    unset($ai_payload['tools']);
    $ai_payload['toolChoice'] = 'none';
    $ai_payload['parallelToolCalls'] = false;
  }

  return $ai_payload;
}, 10, 1);

Example: force a specific tool (when tools exist) #

If tools are present, you can force the model to call one tool.

add_filter('kimaai_chatbot_ai_payload', function (array $ai_payload): array {
  if (empty($ai_payload['tools']) || !is_array($ai_payload['tools'])) {
    return $ai_payload;
  }

  // Force a specific tool by name.
  $ai_payload['toolChoice'] = [
    'type' => 'function',
    'name' => 'wp_search_posts',
  ];

  return $ai_payload;
}, 10, 1);

Make sure the tool name exists in the final tools array after selection filtering.

Example: enforce safe bounds (temperature / max tokens) #

add_filter('kimaai_chatbot_ai_payload', function (array $ai_payload): array {
  // Clamp temperature.
  $t = isset($ai_payload['temperature']) ? (float) $ai_payload['temperature'] : 0.7;
  $ai_payload['temperature'] = max(0.0, min(1.0, $t));

  // Clamp max output tokens.
  $max = isset($ai_payload['maxOutputTokens']) ? (int) $ai_payload['maxOutputTokens'] : 512;
  $ai_payload['maxOutputTokens'] = max(32, min(2048, $max));

  return $ai_payload;
}, 10, 1);

Notes and best practices #

  • This filter is the correct place to modify the outgoing AI request. (By contrast, kimaai_chatbot_before_request is for telemetry.)
  • Keep modifications deterministic and fast—this runs on every chatbot message.
  • Be careful when appending context to prompt: you may hit the plugin’s maxInputLength earlier in the pipeline (note: max length is checked before this filter in your current code, so adding a lot here can still create oversized provider prompts even if the user input passed the check).
  • Don’t add sensitive personal data unless you have a clear reason and consent.

Related hooks #

  • kimaai_chatbot_prompt — normalize/redact user input earlier
  • kimaai_chatbot_gate — allow/block before any AI request is prepared
  • kimaai_chatbot_tools_registry — register tool definitions
  • kimaai_chatbot_before_request — telemetry just before sending
  • kimaai_chatbot_response_payload — modify the AI response before returning to the client
Updated on December 13, 2025