FAQ and Troubleshooting

For end users and support teams. Answers are based on the module's actual behaviour.

FAQ

What exactly does this module do?

It adds a floating AI chat widget. When a visitor asks a question, the module sends the question plus a knowledge context built from your published content to an OpenAI-compatible chat completions API, and shows the answer in the widget. It is not a content module - it renders no content of its own.

Where does the AI get its answers?

From the content you select: published articles in the chosen categories (or every published article if none are selected), FAQ articles in the chosen category, and - only when enabled - published Kunena forum topics. The model is instructed to answer only from that content and to return a fallback answer when it does not cover the question.

Does the module collect analytics or store conversations?

No. It adds no analytics, tracking or telemetry and does not store conversations. It does, however, send the visitor's question and the selected knowledge-base context from your server to the AI endpoint you configure - that is the only data egress, and it goes only to the endpoint in the module settings.

Do I need Kunena?

No. Kunena 6.x is optional and only used when Include Kunena forum topics is set to Yes. With the switch off, the Kunena tables are never queried.

Which AI providers are supported?

Any OpenAI-compatible chat completions API. The default is OpenCode Zen on a paid model variant, so an OpenCode Zen key with credits is required for that default; change the endpoint, key and model to use another provider.

Free or paid?

The module is free and open source, licensed under the GNU GPL v3 or later. The AI service it calls may be paid - with the default OpenCode Zen endpoint you pay the provider, not Bearsampp.

Which Joomla and PHP versions are supported?

Joomla 5.4 or later (Joomla 6 ready) and PHP 8.1 or later.

Is it compatible with Joomla 3 or Joomla 4?

No. The module targets Joomla 5.4+ and Joomla 6 only. Joomla 3 and Joomla 4 are not supported.

Is there an on/off switch for the widget?

Not as a dedicated field - the widget renders wherever the module is published. To hide it, unpublish the module or restrict its menu assignment. Unpublishing is the effective off switch.

Where is the data cached?

The knowledge context is cached server-side through Joomla's cache and rebuilds automatically when the content it was built from changes. The visitor's theme preference is the only thing stored in the browser, in localStorage under mod_bearsamppai_theme.

Does it work with a template override?

Yes. Standard Joomla template overrides apply, and the widget can be restyled from your template with CSS custom properties on .mod-bearsamppai__chat. The Module Class Suffix and Alternate Layout options are on the Advanced tab.

Troubleshooting

The widget does not appear

Confirm the module is published and assigned to the page you are viewing (Menu Assignment), and that its position exists in your template.
Check the browser console for errors and the Network tab for the chat.css and chat.js requests; a missing asset file leaves the widget unstyled or inert.
If another module or script also injects a fixed element into the same corner, it may cover the launcher. Change the Widget position or the offsets.

I get an error bubble instead of an answer

"Missing API key and model for module N. Save the AI Chat tab on that module instance." - the module has no API key and/or model saved. Open the module, fill in the AI Chat tab and save.
"AI API request failed (status 401)" (or 403) - the API key is wrong, expired or lacks access to the model.
"AI API request failed (status 404)" - the model name or endpoint is wrong for your provider.
"AI API request failed (status 400)" - the request was rejected: usually a bad model name or a payload your provider does not accept.
"The AI service is busy right now. Please try again shortly." - both the primary and the fallback model were rate limited or returned a server error. Wait and retry, or check your provider quota.
"The AI service is taking too long to respond." - the fallback request also timed out. Raise the timeouts or switch to a faster model.
"Unexpected response from the AI API" - the endpoint answered but not in the OpenAI chat completions shape. Confirm the endpoint is a chat completions URL.

The assistant always returns the fallback answer

The fallback answer means no knowledge context matched (or none could be built). Check:

Are the relevant articles published and inside a selected Article categories entry (or is the article list empty so everything is in scope)?
Is your FAQ category set, and are the FAQ articles published? In the FAQ category the article title is the question and the text is the answer.
Is the context budget large enough? The Knowledge context limit caps how much content is sent; if much of your content is skipped, narrow the article categories or raise the limit.
Try switching Context ordering between relevance and newest - large, mostly-irrelevant corpora often answer better with relevance, while release-note style sites may prefer newest.

My FAQ entries are ignored

In the newest ordering the FAQ is loaded first but capped at half the context budget so a large article selection cannot starve it. If the FAQ is still being squeezed out, switch to relevance ordering or raise the context limit. Also confirm the FAQ category is actually set and its articles are published.

Answers reference the wrong page or omit a page

The content that did not fit the character budget is skipped whole, not truncated, and the module logs which items were dropped. Enable Show source links (with relevance ordering) to see which pages were used, and adjust the categories or the context limit if an important page is being left out.

The connection status dot is always offline

Confirm Show connection status is enabled; the dot checks a method=ping request that does not call the AI.
A blocked or proxied site, or a firewall in front of index.php, can prevent the ping from reaching com_ajax. Check the Network tab for the method=ping request.
The dot also reports offline when the browser is offline or the tab is hidden; it re-checks when the tab becomes visible.

My theme choice is not remembered

The runtime theme toggle stores the choice in localStorage. In private/incognito windows or when storage is blocked by the browser, the choice cannot be saved and the widget falls back to the configured Default theme (or the system preference on auto).

The copy button does not copy

Copying uses the Clipboard API, which requires a secure context (HTTPS). On an insecure origin the module falls back to a legacy copy path; if the browser blocks that too, the copy fails. Use HTTPS in production.

Keyboard shortcut opens the wrong chat

When several Bearsampp AI widgets are on the same page, Ctrl+/ (or Cmd+/) opens the first one in the page. Click a specific widget's launcher to open that instance.

General debugging tips

Open the browser developer tools Console and Network tabs and watch the request to index.php?option=com_ajax&module=bearsamppai&method=ask&format=json. The JSON body carries success, answer or error.
Check the System → Global Configuration → System → Debug log (or the site's log directory) for mod_bearsamppai.php: it records the context size, which sources were used, ordering and any fallback-model attempt.
Confirm the server can reach the AI endpoint over HTTPS (outbound requests are not blocked).
Test the API key and model against your provider directly to rule out a key or quota problem.