Chatbot Widget Documentation

Basic Implementation

There are two versions of the chatbot widget available:

1. Side Widget

<div id="ae-chatbot-widget" ></div>
<script>
    const ae_widget_config_params = {
        botname: "YourBotName",
        widget_popup_text: "Hello! How can I help you today?",
        styles: {
            "chatbot-brand-primary-color": "#000000",
        },
    }
</script>
<script src="https://chat.ask.thiaplatform.ai/static/js/widget-loader.js"></script>

2. Fullscreen Version

<div id="ae-chatbot-fullscreen"></div>
<script>
    const ae_widget_config_params = {
        botname: "YourBotName",
        widget_popup_text: "Hello! How can I help you today?",
        styles: {
            "chatbot-brand-primary-color": "green",
          },
    }
</script>
<script src="https://chat.ask.thiaplatform.ai/static/js/fullscreen-loader.js"></script>

Style Parameters

Customize the appearance of your chatbot widget using these CSS variables:

Parameter Description Default / Example
--chatbot-brand-primary-color Primary brand color used throughout the widget #f47b28
--chatbot-font-size Base font size for the widget 15px
--chatbot-header-color Color of the header when chatbot is open #ffffff
--chatbot-header-text-color Color used for header text #000000
--chatbot-header-text-weight Boldness of header text, (ie 'normal', 'bold', 'lighter') normal
--chatbot-footer-text-color Color used for footer text, semi-transparent until hovered #ffffff
--chatbot-reference-background Color used for inline citation background #f0721f;
--chatbot-reference-text-color Color used for inline citation text #ffffff
--chatbot-reference-link-background Background color used for reference links at the bottom of the message #f0721f
--chatbot-reference-link-text-color Text color used for reference links at the bottom of the message #ffffff
--chatbot-icon-img URL to the chatbot's avatar image url(./assets/chatbotAvatar.png)
--chatbot-icon-background-color Color fill behind the icon var(--chatbot-brand-primary-color)
--chatbot-icon-size Size of the chat icon 50px
--chatbot-icon-roundness Corner radius of the icon 20%
--chatbot-icon-border Border style for the icon none
--chatbot-icon-shadow Drop shadow for the icon none
--chatbot-icon-offset Distance from bottom and right sides var(--chatbot-font-size)
--chatbot-icon-hover-color Fill color on hover var(--chatbot-brand-primary-color)
--chatbot-icon-hover-border Border style on hover none
--chatbot-icon-hover-shadow Drop shadow on hover -2px 4px 2px rgba(0, 0, 0, 0.2)
--chatbot-modal-width Chat window width 450px
--chatbot-modal-margin Distance from screen edges 0px
--chatbot-modal-radius Window corner radius 0
--chatbot-modal-border Window border style none
--chatbot-modal-background Main window background color white
--chatbot-modal-shadow Window drop shadow -2px 4px 8px rgba(0, 0, 0, 0.1)
--chatbot-modal-button-radius Button corner radius 4px
--chatbot-message-radius Message bubble corner radius var(--chatbot-font-size)
--chatbot-bot-text-color Bot message text color black
--chatbot-bot-text-background Bot message background color hsl(0, 0%, 96%)
--chatbot-user-text-color User message text color white
--chatbot-feedback-icon-color Changes the color of the icons at the bottom of messages black
--chatbot-user-text-background User message background color var(--chatbot-brand-primary-color)
--chatbot-icon-face-color Fullscreen icon face color #f47b28
--chatbot-icon-hat-color Fullscreen icon hat color #81858b
--chatbot-icon-eye-color Fullscreen icon eye color #045db3
--chatbot-link-color Hyper link text color #3366cc

Configuration Parameters

Pass these via ae_widget_config_params at page load, or update them mid-conversation by sending an update_config frame over the WebSocket. Options listed for weighting fields are case-insensitive.

Parameter Description Default / Options
Bot Identity
botname Display name for the bot. Used by the frontend in default greeting text. "ExtensionBot"
widget_popup_text Banner text shown beside the closed widget. "Hi, I'm ${botname}. đź‘‹ How can I help you?"
greeting_text Initial bot bubble shown when the widget opens. The backend reads this only to decide whether to suppress its own default greeting. "Hi! My name is ${botname}. I can help you with your extension-related questions…"
Locality & Source
state User's home state. Full name, case-insensitive. Drives retrieval localization and the extension-office contact directory when extension_office_url is unset. ""
list_of_states Array of state names to prefer during retrieval. Full names, case-insensitive. state is appended automatically if set. []
source Preferred source domain (root domain, e.g. okstate.edu). Honored when local_weighting is anything other than "none". ""
local_weighting High-level locality preference. none = no preference; slight/moderate/strong progressively downweight out-of-state / off-source chunks; complete = only matching chunks are retrieved. "none"
none · slight · moderate · strong · complete
date_weighting How heavily to prefer recent content. none disables date decay; slight through complete apply a sigmoid decay around the 5-year mark. "slight"
none · slight · moderate · strong · complete
Retrieval & Generation
model_name Pins the generation model to a specific OpenRouter model slug (e.g. openai/gpt-5.4, anthropic/claude-opus-4.8). When set, it overrides the model the widget would otherwise use — both the built-in default and any model an SME picks from the in-app dropdown. Leave empty to use that selection. The slug must be reachable by the deployment's OpenRouter key; unknown slugs fail server-side. ""
max_num_resources_returned Upper bound on the number of references returned per turn. Clamped server-side to [3, 20]. 10
max_images_per_message Maximum number of images a user can attach to a single message. Hard-capped at 5 server-side, so values above 5 have no additional effect. 5
streaming Stream the final answer token-by-token over the WebSocket. Has no effect on POST /api/chat, which always returns a single buffered response. true
Tools
use_weather Allow the bot to look up current and forecast weather for the user's location (uses state / county). true
use_cowculator Allow the bot to build cowculator forms (beef-cattle ration evaluation). false
use_web_search Allow the bot to use web search as a backup to the knowledge base. Automatically skipped when local_weighting or topic_weighting is "complete". true
Contact
extension_office_url Override URL for the user's local extension office contact page. When set, the bot uses this directly instead of the state-keyed contact directory. ""
Fullscreen Mode
fullscreen_header_text Header copy on the fullscreen variant. "How can I help you?"
fullscreen_icon_image_url URL of the icon to display in the fullscreen application. ""
minimal_fullscreen Cleaner fullscreen landing page: a small icon sits inline with fullscreen_header_text, the botname and default question cards are hidden, and the input uses subtler styling. Footer links (Terms / Privacy / About) always remain. false
remove_headings Fullscreen only: hide the landing icon and fullscreen_header_text entirely, leaving just the input box (plus the question cards, unless minimal_fullscreen is also set). Footer links still remain. false
fullscreen_default_questions Default question cards shown when the fullscreen widget opens. Array of { header, question } objects. [ { header: "Lawn and Garden", question: "What is the best fertilizer to use on my lawn?" }, { header: "Local Extension Office", question: "How do I contact my local extension office?" }, { header: "Crop Management", question: "What are some effective ways to manage my crops?" }, { header: "Pest Management", question: "Can I use Bacillus thuringiensis and spinosad together…?" }, ]
Conversation History
conversation_history Master switch for the local conversation-history feature (saved conversations + search, in the widget header and the fullscreen rail). History is stored in the visitor's browser via localStorage, scoped to your domain — it is never sent to the server, and it is not shared across different domains. Set false to disable the feature and hide its UI entirely (e.g. if your page already relies heavily on localStorage). true
max_conversations Maximum number of conversations kept in local history. Once exceeded, the oldest conversations are evicted first. Lower this to reduce the widget's localStorage footprint. 50
max_history_bytes Soft cap (in bytes) on total local-history size. Oldest conversations are evicted to stay under it, and writes that would exceed the browser's quota fall back to evicting too. Default is ~4 MB. 4194304

Widget Builder

Generated Code

About

ExtensionBot is a LLM Agnostic chatbot that is built and deployed by the Extension Foundation. We are working closely with Thia Corporation on the development and deployment of the technology. ExtensionBot is backed by an LLM (Large Language Model) that is trained exclusively on data provided by Cooperative Extension institutions and Ask Extension. Learn more at https://extension.org/tools/extbot/

Changelog

Recent ExtensionBot releases, newest first.

Loading…