An add-on is a WordPress plugin that extends KimaAI through its hooks. Its main file registers an add-on class on kimaai_register_addons, and KimaAI starts the class once its own services are ready: the class adds the add-on’s hooks and, in a WP-CLI run, its commands. Nothing of it runs on a site without KimaAI. This guide builds an add-on that tells the chatbot about the shop’s holidays: a plugin file, the add-on’s class, and a command that shows the notice.
Example
/**
* Plugin Name: My holiday notice for KimaAI
* Description: Tells the KimaAI chatbot when the shop is closed.
* Version: 1.0.0
*/
defined('ABSPATH') || exit;
add_action(
'kimaai_register_addons',
function (\KimaAI\Addons\AddonManager $manager): void {
require_once __DIR__ . '/src/HolidayAddon.php';
$manager->register(new \MyHolidayNotice\HolidayAddon());
}
);
This is the plugin’s main file, my-holiday-notice/my-holiday-notice.php. It adds the callback when WordPress loads the plugin, before KimaAI fires the action on plugins_loaded. The class is required inside the callback, so its file loads only when KimaAI runs: it implements KimaAI’s interface, which does not exist without KimaAI, and a plugin that declares the class at the top of its main file stops the site with a fatal error when KimaAI is inactive or loads later.
The add-on’s class
my-holiday-notice/src/HolidayAddon.php:
<?php
namespace MyHolidayNotice;
use KimaAI\Addons\AddonInterface;
use KimaAI\Main;
use KimaAI\Surfaces\ClassesSurface;
defined('ABSPATH') || exit;
final class HolidayAddon implements AddonInterface {
public function register(Main $main, ClassesSurface $classes): void {
add_filter('kimaai_chatbot_instructions', [$this, 'addNotice']);
}
public function registerCommands(Main $main, ClassesSurface $classes): void {
\WP_CLI::add_command('my-holiday-notice show', [$this, 'showNotice']);
}
public function addNotice(string $instructions): string {
$notice = $this->notice();
return $notice === '' ? $instructions : $instructions . "\n" . $notice;
}
/**
* Shows the notice the chatbot gets.
*/
public function showNotice(): void {
$notice = $this->notice();
\WP_CLI::log($notice === '' ? 'No holiday notice is set.' : $notice);
}
private function notice(): string {
return trim((string) get_option('my_holiday_notice', ''));
}
}
register() is the one method of KimaAI\Addons\AddonInterface. The add-on adds its hooks there; here it adds the notice from the option my_holiday_notice to the chatbot’s instructions. registerCommands() is optional: KimaAI calls it in a WP-CLI run, so wp my-holiday-notice show prints the notice.
When it starts
On every request, on plugins_loaded at priority 10, KimaAI:
- builds its services and registers its own hooks,
- fires
kimaai_register_addons, where add-ons register, - calls
register()of each add-on, in the order they registered, - fires
kimaai_loaded, - in a WP-CLI run, calls
registerCommands()of each add-on that has one, oncli_init.
WordPress’s init comes later, so an add-on can still add callbacks to it in register(). Keep register() to adding hooks: it runs on every page view, the admin and REST requests included.
The services
$main and $classes give access to KimaAI’s own objects: $classes->get(<class name>) returns the service of a class. They are KimaAI’s internal classes, not a public interface, and they can change in any release. Build on hooks where one fits; the hook pages list them by area.
Without an add-on class
A few hooks need no class. kimaai_loaded fires once KimaAI and its add-ons are loaded and not at all without KimaAI:
add_action(
'kimaai_loaded',
function (): void {
add_filter(
'kimaai_chatbot_instructions',
function (string $instructions): string {
return $instructions . "\nOur support line is open Monday to Friday, 9:00 to 17:00.";
}
);
},
10,
0
);
Next steps
- A settings page for the add-on: the guide “Your own setting field” (
docs/guides/field-components.md). - A tool the chatbot can call: the guide “A tool for the chatbot” (
docs/guides/custom-tool.md).
Related
- kimaai_register_addons: registers the add-on.
- kimaai_loaded: fires once KimaAI and its add-ons are loaded.
- kimaai_chatbot_instructions: the filter the example uses.