kimaai_chatbot_theme Filter #

The kimaai_chatbot_theme filter lets you override or extend the chatbot’s theme colors (CSS variables) generated by the plugin.

It runs when the plugin builds the inline :root { --kimaai-chatbot-* } CSS, right before that CSS is injected via wp_add_inline_style().

---

When it runs #

During asset enqueue (enqueueAssets()), the plugin calls:

1. generateDynamicCss()
2. inside that method, it reads appearance options and builds a $theme array
3. it applies the filter:

$appearance = apply_filters('kimaai_chatbot_theme', $theme);

4. it outputs the CSS variables based on the filtered values.

---

Filter signature #

/**
 * Filter the chatbot appearance settings.
 *
 * @param array $vars The appearance variables.
 * @return array The modified appearance variables.
 */
$appearance = apply_filters('kimaai_chatbot_theme', $theme);

Parameters #

$theme (array) #

An associative array of theme variables (colors) used to generate CSS variables:

• bodyBgColor
• bodyTextColor
• userMessageBgColor
• userMessageTextColor
• aiMessageBgColor
• aiMessageTextColor

Return value #

Return the same array shape, with any values changed:

return [
  'bodyBgColor' => '#...',
  'bodyTextColor' => '#...',
  // ...
];

---

What it affects #

The values map to CSS variables like:

• --kimaai-chatbot-primary
• --kimaai-chatbot-body
• --kimaai-chatbot-text
• --kimaai-chatbot-user-message-background
• --kimaai-chatbot-user-message-text
• --kimaai-chatbot-ai-message-background
• --kimaai-chatbot-ai-message-text

These variables are set on :root, so they apply globally wherever the chatbot UI uses them.

---

Basic example: override all colors #

Add this to a custom plugin or your theme’s functions.php:

add_filter('kimaai_chatbot_theme', function (array $theme): array {
  $theme['bodyBgColor'] = '#0b1020';
  $theme['bodyTextColor'] = '#ffffff';

  $theme['userMessageBgColor'] = '#2563eb';
  $theme['userMessageTextColor'] = '#ffffff';

  $theme['aiMessageBgColor'] = '#111827';
  $theme['aiMessageTextColor'] = '#e5e7eb';

  return $theme;
});

---

Example: apply dark mode automatically #

This example switches the chatbot theme based on the site setting is_admin_bar_showing() (just as a simple toggle). Replace with your own detection logic (cookie, user meta, theme option, etc.).

add_filter('kimaai_chatbot_theme', function (array $theme): array {
  $dark_mode = (bool) get_option('my_site_dark_mode', false);

  if (!$dark_mode) {
    return $theme; // keep defaults from settings
  }

  return array_merge($theme, [
    'bodyBgColor' => '#0f172a',
    'bodyTextColor' => '#e2e8f0',
    'userMessageBgColor' => '#38bdf8',
    'userMessageTextColor' => '#0b1220',
    'aiMessageBgColor' => '#111827',
    'aiMessageTextColor' => '#e5e7eb',
  ]);
});

---

Example: enforce safe fallbacks (validation) #

Because this filter can receive unexpected values (from settings or other filters), it’s good practice to validate.

add_filter('kimaai_chatbot_theme', function (array $theme): array {
  $defaults = [
    'bodyBgColor' => '#ffffff',
    'bodyTextColor' => '#111111',
    'userMessageBgColor' => '#2563eb',
    'userMessageTextColor' => '#ffffff',
    'aiMessageBgColor' => '#f3f4f6',
    'aiMessageTextColor' => '#111111',
  ];

  // Ensure all keys exist.
  $theme = array_merge($defaults, $theme);

  // Very lightweight validation: keep only strings.
  foreach ($theme as $k => $v) {
    if (!is_string($v) || $v === '') {
      $theme[$k] = $defaults[$k];
    }
  }

  return $theme;
});

---

Notes and best practices #

• This filter only controls the CSS variable values the plugin outputs. It does not change layout, spacing, or typography unless the UI is built to use those variables.
• Because the CSS variables are set on :root, your changes apply anywhere the chatbot is rendered on the page.
• Keep contrast/accessibility in mind (text vs. background).

---

Related customization points #

• Shortcode:
  to place the bot
• kimaai_chatbot_prompt to normalize incoming prompts
• kimaai_chatbot_gate to block/allow requests
• kimaai_chatbot_tools_registry to register tools
• kimaai_chatbot_ai_payload to adjust the provider request payload