Tutorial: Install and Configure Bearsampp AI

A step-by-step guide for site builders. Suitable for Joomla.org documentation or a knowledgebase article.

Before you begin

You need:

Joomla 5.4 or later (Joomla 6 is supported). Joomla 3 and Joomla 4 are not supported.
PHP 8.1 or later.
An OpenAI-compatible chat completions API key. With the default endpoint (OpenCode Zen) this is an OpenCode Zen key with credits.
Outbound HTTPS access from the server to your AI endpoint.
Optionally, Kunena 6.x if you want to ground answers in forum topics.
Content to answer from: published articles in the categories you want to expose, and/or a FAQ category.

The assistant only knows what you point it at. Bearsampp AI does not crawl your site on its own. You choose the article categories, the FAQ category and (optionally) the forum topics. Until you configure at least one source and add an API key, the widget will render but cannot answer.

Step 1 - Install the module

Download the release ZIP (mod_bearsamppai_<version>.zip) from https://github.com/Bearsampp/mod_bearsamppai/releases
In the Joomla Administrator, go to System → Install → Extensions.
On the Upload Package File tab, drop the ZIP onto the upload area.
Wait for the "Installation of the module was successful" message.

The ZIP must contain the module files at its root (mod_bearsamppai.xml, mod_bearsamppai.php, helper.php, services/, src/, tmpl/, media/, language/), not nested in an extra folder. The official release ZIPs are already packaged correctly.

Step 2 - Create the module

Go to Content → Site Modules.
Click New and choose Bearsampp AI.
Give the module a Title (for example, "Support assistant").

The widget is rendered wherever the module is published; the module has no content to display on its own.

Step 3 - Configure the knowledge base

On the Knowledge Base Content tab:

Option	Set it to	Notes
Article categories	one or more categories	Published articles in these categories are used as context. An article counts if it is in any selected category. Leave empty to use every published article site-wide.
FAQ category	your FAQ category	Each article's title is read as the question and its text as the answer. Leave empty for no FAQ content.
Include Kunena forum topics	`No` (default)	Set to Yes only if you want recent published Kunena topics in the context. Requires Kunena 6.x; if Kunena is missing the source is simply skipped.

There is no per-source item count. Everything published in a selected scope is a candidate, and the Knowledge context limit is the only cap.

Step 4 - Configure the AI

On the AI Chat tab:

Option	Default	What it does
AI API key	(empty)	Your key for the AI service. With the default endpoint this is an OpenCode Zen key.
AI model	`glm-5.3-flash`	The model to use.
AI endpoint	OpenCode Zen	An OpenAI-compatible chat completions endpoint. Change it (and the model/key) to use another provider.
Fallback model	`deepseek-v4-flash`	Tried once after a timeout, HTTP 429 or 5xx. Blank disables it.
Max response tokens	`512`	64–4096.
Temperature	`0.2`	0–1. Low keeps answers factual.
Request timeout (seconds)	`30`	5–120.
Fallback timeout (seconds)	`10`	1–120; applies only to the fallback-model request.
Knowledge context limit (characters)	`20000`	1000–200000. The budget for all context sent to the AI.
Context ordering	`relevance`	`relevance` ranks candidates against each question; `newest` favors the most recent content.
Show source links	`Yes`	List the pages an answer came from (used with `relevance` ordering).
Fallback answer	`I'm sorry, I don't know how to answer that`	Returned when the knowledge base has no relevant content. The API is not called in that case.

Leave the other fields at their defaults until you have a working chat; they only affect presentation.

Step 5 - Tune the widget appearance

Option	Default	What it does
Chat button label	`Ask Bearsampp`	Text on the floating button and the panel header.
Input placeholder	`Ask a question about Bearsampp...`	Placeholder in the message box.
Widget position	`bottom-right`	bottom-right, bottom-left, middle-right, middle-left.
Panel width / height (px)	`400` / `500`	Resizable within 260–900 and 300–1200.
Horizontal / vertical offset (px)	`20` / `20`	0–200 from the viewport edge.
Show button label on mobile	`No`	No: a round 48px launcher on phones. Yes: keep the text.
Default theme	`auto`	auto, light or dark; visitors can toggle at runtime.
Show copy conversation button	`Yes`	Adds the transcript-to-clipboard button.
Welcome message	(default text)	Optional first assistant message; empty for no greeting.
Show connection status	`No`	Adds a dot that checks the endpoint periodically.
Status check interval (seconds)	`30`	10–600.

Advanced options (Module Class Suffix, Alternate Layout, caching) are on the Advanced tab. The widget can also be restyled from your template with CSS custom properties on .mod-bearsamppai__chat.

Step 6 - Publish and assign

Choose a Position available in your template. Because the widget is fixed to the viewport corner it does not matter which position it occupies, as long as the module is published on the pages where you want the chat.
On the Menu Assignment tab, select the pages that should show the chat. To show it site-wide, choose On all pages.
Set Status to Published.
Click Save & Close.

Step 7 - Verify

Open the front end where the module is assigned. The floating button should appear in the configured corner.
Open the chat and ask a question whose answer exists in the content you selected; the answer should reference that content.
Ask something outside the knowledge base; you should get the fallback answer.
Open your browser developer tools and check the Network tab: the request to index.php?option=com_ajax&module=bearsamppai&method=ask&format=json should return HTTP 200 with a JSON body.
Toggle the theme and reload; the choice should be remembered.

Adding more knowledge later

Add categories to Article categories, add articles to the FAQ category, or switch on forum content, then save. The server-side context cache is invalidated automatically when the content it was built from changes, so new or edited pages are picked up without an explicit clear.