Chatbot API

View as Markdown

New to chatbots? General gives an overview. This page covers chatbots in code: rendering one from PHP, adding markup to it, controlling it from JavaScript, and managing saved chatbots over REST.

Render a chatbot from PHP

sleekAi_render_chatbot() prints a chatbot widget built from an array instead of a chatbot saved in the editor. Call it where your theme prints markup, for example on wp_footer:

PHP

add_action('wp_footer', function () {
    if (!function_exists('sleekAi_render_chatbot') || !is_singular('product')) {
        return;
    }

    $productId = get_queried_object_id();

    sleekAi_render_chatbot([
        'model' => [
            'model' => 'openai-gpt-4.1-mini',
        ],
        'data' => [
            'instruction' => 'You answer questions about the product {title}. '
                . 'Its description is: {description}',
            'variables' => [
                'title' => get_the_title($productId),
                'description' => wp_strip_all_tags(get_post_field('post_content', $productId)),
            ],
        ],
        'widget' => [
            'button' => [
                'text' => 'Ask about this product',
            ],
        ],
    ]);
});

model.model is required. It takes the same provider-and-model identifiers as the Developer API.
Each key in data.variables replaces the matching {key} in data.instruction. Values must be strings, and only a variable with exactly that key replaces a placeholder.
SleekAI wraps the instruction in the same fixed guidelines as every chatbot.
Nothing renders while no API key is stored.

Chat requests do not receive the array from the page. SleekAI stores it in a transient for a week, renewed at most daily when rendered, named sleek-ai_chatbot_data_ followed by the key you pass or, without a key, by an MD5 hash of the array. Requests read it from there. With a fixed key, the stored array stays the same until its next daily renewal. Use a key only for data shared by every visitor, and include a content revision when the data changes. The server-side lifetime must exceed the lifetime of cached pages that carry its key.

Cacheable public context

Inline chatbots can set 'visitorContext' => 'anonymous'. This opts just that render into public context: its bootstrap has no login nonce, its signed user scope is zero, and completion and polling requests omit browser credentials. Anonymous and logged-in visitors receive identical widget markup. The default remains the current user’s context. Each widget carries its own bootstrap, so public and personalized widgets can coexist without sharing authentication.

For a saved chatbot, use visitor_context="anonymous" on its shortcode. Its published status and display conditions still apply. Automatic widgets can select context per render through sleekAi/chatbot/visitorContext, whose second argument is that widget’s chatbot settings. Returning anonymous changes no stored bot or global WordPress user. Signed completion authorization remains unchanged; public context does not grant access to private chatbot posts.

Options

The array follows the shape of a saved chatbot. These are the keys a chatbot rendered from PHP reads, with the values SleekAI uses when a key is missing:

PHP

sleekAi_render_chatbot([
    // Optional. Names the transient and the key markup filter.
    'key' => 'support',
    'model' => [
        // Required. Provider and model identifier.
        'model' => 'openai-gpt-4.1-mini',
    ],
    'data' => [
        'instruction' => '',
        // Strings keyed by variable name.
        'variables' => [],
    ],
    'widget' => [
        'general' => [
            // Shows a button that switches the chat to fullscreen.
            'fullscreen' => false,
        ],
        'position' => [
            'alignment' => 'right', // 'left' or 'right'
            'distance' => '16px',
        ],
        'button' => [
            'type' => 'button', // 'button' or 'logo'
            'text' => 'Chat with AI',
            'color' => '#000000',
            'backgroundColor' => '#FFFFFF',
            'borderColor' => '#E4E4E7',
            'borderRadius' => '8px',
            'fontSize' => '0.875rem',
            'logo' => [
                // Image shown on the button when type is 'logo'.
                'url' => null,
            ],
        ],
        'chat' => [
            'initialMessage' => null,
            'inputText' => 'Send a message',
            'nameAi' => 'SleekAI',
            'theme' => 'light', // 'light', 'dark' or 'dark-wordpress'
            'presets' => [
                'label' => '',
                // Strings, or arrays with a 'value' key.
                'items' => [],
            ],
        ],
        'logo' => [
            // Image shown in the chat window's header.
            'url' => null,
        ],
        'storage' => [
            'type' => 'none', // 'none', 'sessionStorage' or 'indexeddb'
        ],
        'messages' => [
            'menu' => [
                'chatFromHere' => false, // needs 'indexeddb' storage
                'regenerate' => false,
                'delete' => false,
            ],
        ],
    ],
]);

The Widget page describes what each setting does, and the button options set the CSS custom properties described in Styling.

The public renderer represents an absent button logo, header logo or welcome message as null; the widget treats those three values as empty strings while retaining the other saved settings. Numbers, objects and other malformed string values still fail validation.

The configured widget.chat.theme applies to both the chatbot and its frame. light stays light regardless of the visitor’s system preference; dark and dark-wordpress use dark mode.

Add markup to a chatbot

SleekAI has no filter that changes a chatbot’s settings before it renders. Change saved chatbots in the editor, and build chatbots that differ per page with sleekAi_render_chatbot(). Three filters add markup, usually a <style> element, which SleekAI inserts into the chatbot’s frame:

sleekAi/chatbot/markup for every chatbot.
sleekAi/chatbot/key={key}/markup for a chatbot rendered from PHP, where the key is sleek-ai_chatbot_data_ followed by its key.
sleekAi/chatbot/id={id}/markup for a chatbot saved in the editor, by its post ID.

They run in that order, each with the markup so far and the chatbot’s array:

PHP

add_filter('sleekAi/chatbot/key=sleek-ai_chatbot_data_support/markup', function ($markup, $chatbot) {
    return $markup . '<style>:root { --sleek-ai--chatbot-button--padding: 10px 14px; }</style>';
}, 10, 2);

The hooks reference lists their arguments.

JavaScript API

The script that SleekAI prints with the first chatbot on a page defines window.SleekAI.chatbot:

JavaScript

// Open the first chatbot on the page, or open it in fullscreen.
SleekAI.chatbot.open()
SleekAI.chatbot.open({ fullscreen: true })

// Close it again.
SleekAI.chatbot.close()

// Hide the widget and its button, for example while another modal is open,
// and show it again.
SleekAI.chatbot.hide()
SleekAI.chatbot.show()

// Every method takes the chatbot's position on the page.
SleekAI.chatbot.hide({ index: 2 })

index is not the chatbot’s ID. It counts every chatbot on the page, embedded chats included, in the order SleekAI renders them, starting at 1. Shortcodes in the page content render before the saved widget chatbots, which SleekAI adds in the footer. hide() and show() act on floating widgets only.

When chatbots load

A visitor who never uses a chatbot downloads only its button and settings. A floating chatbot loads its frame when a pointer moves onto its button, the button takes focus or a finger touches it, so it is usually ready by the time the visitor clicks. A click that arrives sooner shows the button busy and opens the chat as soon as it has loaded. The framed button then replaces the page’s button in place and keeps its focus. An embedded chat loads when it comes within 400 pixels of the viewport, in browsers without IntersectionObserver at once. SleekAI.chatbot.open() loads a chatbot that has not loaded yet and opens it once it has; close() acts on loaded chatbots only.

REST management

Administrators can manage saved chatbots through SleekAI’s REST operations, with normal WordPress REST authentication such as a REST nonce or an application password:

Chatbot_list lists every chatbot.
Chatbot_create creates a chatbot. Every call creates another one.
Chatbot_read returns one chatbot.
Chatbot_update replaces a chatbot’s saved definition.
Chatbot_remove deletes a chatbot and its synchronized files.

The REST reference gives their methods and paths, under sleek-ai/v1/chatbot. Every one requires the manage_options capability.

Chatbot_update replaces, it does not merge. Always send the full chatbot returned by Chatbot_read; omitted sections are removed and the editor shows their defaults. wp sleek ai chatbot create and wp sleek ai chatbot update do the same from the command line, from a JSON file.