kimaai_chatbot_before_request Hook #

The kimaai_chatbot_before_request action fires immediately before the plugin sends the request to the configured AI provider (via AiService::run()).

Use it to add logging, performance timing, metrics, debugging, request auditing, or to attach metadata to your own telemetry—without modifying the request.

---

When it fires #

After the plugin has:

• validated nonce
• applied prompt normalization (kimaai_chatbot_prompt)
• passed the gate (kimaai_chatbot_gate)
• enforced rate limits and max input length
• resolved and filtered tools (including user-selected tools)
• built the final $ai_payload (and applied kimaai_chatbot_ai_payload)

…it triggers:

do_action('kimaai_chatbot_before_request', $ai_payload, $payload, $chatbot_settings);

Then it calls the AI service:

$response = $this->ai_service->run($ai_payload, 'chat');

---

Hook signature #

/**
 * Action: fired just before the AI request is sent (for logging/metrics).
 *
 * @param array $ai_payload
 * @param array $payload
 * @param array $chatbot_settings
 */
do_action('kimaai_chatbot_before_request', $ai_payload, $payload, $chatbot_settings);

Parameters #

1) $ai_payload (array) #

The provider-ready payload that will be sent to the AI service. Typically includes:

• prompt (string)
• postId (int)
• sessionId (string)
• aiProvider (string)
• aiModel (string)
• temperature (mixed/float)
• maxOutputTokens (int)
• optionally tools (array) and tool controls such as toolChoice, parallelToolCalls

Note: $ai_payload is the result after kimaai_chatbot_ai_payload filter has run, so it reflects any last-minute modifications.

2) $payload (array) #

Normalized request context, usually including:

• prompt (string) — normalized prompt
• postId (int)
• sessionId (string)
• selectedTools (string[])
• chatbot_settings may be present later in the flow, but treat $chatbot_settings as the primary settings source.

3) $chatbot_settings (array) #

The chatbot settings used for this request (max limits, provider/model config, etc.).

---

Basic usage: log outgoing request metadata #

add_action('kimaai_chatbot_before_request', function ($ai_payload, $payload, $chatbot_settings) {
  error_log(sprintf(
    '[KimaAI Chatbot] Sending AI request: provider=%s model=%s session=%s postId=%d tools=%d',
    (string) ($ai_payload['aiProvider'] ?? ''),
    (string) ($ai_payload['aiModel'] ?? ''),
    (string) ($payload['sessionId'] ?? ''),
    (int) ($payload['postId'] ?? 0),
    !empty($ai_payload['tools']) ? count($ai_payload['tools']) : 0
  ));
}, 10, 3);

---

Example: record metrics (latency pairing) #

A common pattern is to store a “start time” keyed by session/request, then compute latency in kimaai_chatbot_after_response or kimaai_chatbot_error.

add_action('kimaai_chatbot_before_request', function ($ai_payload, $payload) {
  $session_id = (string) ($payload['sessionId'] ?? '');
  if ($session_id === '') {
    return;
  }

  // Store a timestamp for later (very short retention).
  set_transient('kimaai_ai_start_' . md5($session_id), microtime(true), 5 * MINUTE_IN_SECONDS);
}, 10, 3);

Then in your after-response hook:

add_action('kimaai_chatbot_after_response', function ($response, $ai_payload, $payload) {
  $session_id = (string) ($payload['sessionId'] ?? '');
  $key = 'kimaai_ai_start_' . md5($session_id);

  $start = (float) get_transient($key);
  if ($start > 0) {
    delete_transient($key);
    $ms = (microtime(true) - $start) * 1000;

    error_log(sprintf('[KimaAI Chatbot] AI latency: %.0fms (session=%s)', $ms, $session_id));
  }
}, 10, 5);

---

Example: privacy-aware request auditing (avoid logging prompt) #

If you need to trace requests without storing user text, hash the prompt.

add_action('kimaai_chatbot_before_request', function ($ai_payload, $payload) {
  $prompt = (string) ($ai_payload['prompt'] ?? '');
  $prompt_hash = $prompt !== '' ? hash('sha256', $prompt) : '';

  $audit = [
    'time'        => time(),
    'provider'    => (string) ($ai_payload['aiProvider'] ?? ''),
    'model'       => (string) ($ai_payload['aiModel'] ?? ''),
    'postId'      => (int) ($ai_payload['postId'] ?? 0),
    'sessionId'   => (string) ($ai_payload['sessionId'] ?? ''),
    'tools_count' => !empty($ai_payload['tools']) ? count($ai_payload['tools']) : 0,
    'prompt_hash' => $prompt_hash,
  ];

  error_log('[KimaAI AI Audit] ' . wp_json_encode($audit));
}, 10, 3);

---

Important notes #

• This is an action, not a filter. You can mutate arrays in PHP by reference-like behavior if you modify the passed array variable in your callback, but you should not rely on that here. If you want to intentionally modify the outgoing AI request, use the dedicated filter:
  • kimaai_chatbot_ai_payload
• Don’t echo or output anything—this runs during a REST request.
• Be careful with sensitive data:
  • avoid logging raw prompts unless necessary
  • consider hashing/anonymizing IPs or identifiers you store

---

Related hooks #

• kimaai_chatbot_ai_payload (filter) — modify the outgoing AI provider request body
• kimaai_chatbot_after_response (action) — telemetry after success
• kimaai_chatbot_error (action) — telemetry on exceptions
• kimaai_chatbot_gate / kimaai_chatbot_blocked — early allow/block stage before any AI request is made