FVTV Chatbot (El Savio) — documentation

FVTV Chatbot · Joomla · Documentation

FVTV Chatbot (El Savio) — documentation

FVTV Chatbot installs a floating AI chat widget on every page of your Joomla site. Visitors ask in their own language and get answers about your services, weather and news — generated by NVIDIA NIM, with the API key kept strictly server-side. The one-zip package installs two extensions: com_fvtvchatbot (admin backend, JSON endpoints, DB tables) and plg_system_fvtvchatbot (injects the widget into the frontend).

What it is

FVTV Chatbot (storefront slug pkg_fvtvchatbot) is a production Joomla package for tourism and service sites. Everything runs inside your install — the browser only talks to your site, which calls NVIDIA NIM server-side.

• NVIDIA NIM engine — OpenAI-compatible chat-completions, 15 models (Llama, Nemotron, Mistral, Gemma 3, gpt-oss, Qwen).
• Live context & 11 languages — weather / waves / wind / tides (Open-Meteo) and up to three RSS feeds in the prompt; plus FAQ bypass (zero-credit answers) and off-offer email / webhook alerts.
• WordPress twin — a matching plugin (wp-fvtv-chatbot) exists with the same Options; this manual covers the Joomla package.

Requirements

From the package manifests: Joomla 5.1.0+ (5.1+ and 6.x) and PHP 8.2.0+; MySQL / MariaDB (install SQL creates the component tables, including #__fvtvchatbot_rate); the PHP sodium extension (encrypts the API key; required); outbound HTTPS to integrate.api.nvidia.com, api.open-meteo.com and marine-api.open-meteo.com; and an NVIDIA NIM key (an nvapi-… key, free tier at build.nvidia.com).

Check Extensions → Manage for the installed version; the package and its system plugin ship in lockstep.

Install

1. System → Install → Extensions — upload the single package zip; it installs both extensions.
2. Confirm System - fvtvchatbot is enabled under System → Manage → Plugins — the widget only injects while it is enabled.
3. Enter your Download Key in System → Update → Update Sites (the dlid) or the Licence Options tab (download_key), which re-applies it. Never click “Rebuild Update Sites” — it wipes the keyed feed URL.
4. Open Components → FuerteventuraTV Chatbot — three views: Dashboard, Off-offer notifications, FAQ (NVIDIA bypass). The widget stays hidden on the frontend until the licence resolves valid.

Set up the NVIDIA key and choose a model

In Options, open the NVIDIA NIM API tab:

Save, then on the Dashboard click Test NVIDIA API — it fires a tiny prompt and decodes NVIDIA’s status (codes under Troubleshooting). The key is decrypted server-side only at call time, sent as a Bearer header, and redacted from logs.

Place the widget

No module, no shortcode — placement is automatic. On onBeforeCompileHead the plugin injects the CSS/JS and client config directly (so it works under YOOtheme and custom templates); on onAfterRender it appends the mount <div id="fvtv-chatbot-root" data-fvtv-chatbot></div> before </body>. Show it where you want from Widget Appearance: show_on_routes (one route per line; * = everywhere, /path/* = prefix) and show_on_menu_item_ids scope the pages; position and the #af010c→#134998 gradient set the look; hide_when_vokira_present (default Yes) hides the bot where Vokira Web is configured. Plugin params add exclude_components (default com_users,com_finder) and enable_on_admin (default No).

It injects only on frontend HTML pages (format=html) — never on JSON/RAW, CLI/API, admin auth/installer/config screens, or when unlicensed.

Persona and system prompt (“El Savio”)

“El Savio” is the nickname for the assistant’s built-in persona. It is assembled per language by SystemPromptBuilder; its identity comes from real Options on the FVTV Offered Services tab, not a hard-coded name:

• Default brand: while assistant_name stays FuerteventuraTV, all 11 languages get the full Fuerteventura guide prompt (beaches, surf, excursions, food, legends) plus the FVTV service list.
• Tune it with assistant_role (role), personality (tone), system_prompt_extra (free-form rules), excursions (your service list, overriding the FVTV baseline) and custom_kb (a knowledge base injected into every prompt as the most recent info).
• White-label: rename assistant_name away from FuerteventuraTV and the builder switches to a neutral, option-driven prompt with no Fuerteventura identity, answering only from your excursions / custom_kb.
• Scope limit & off-offer: the prompt keeps the bot on-topic; for an off-list request the model appends a hidden [[NOTIFY:…]] tag, stripped from the reply and turned into a notification. Per-language welcome_{en,it,es} greetings and quick_{en,it,es} reply chips can also override the defaults.

Configuration

In Options (applied on Save), beyond Licence, NVIDIA NIM API, Widget Appearance (above) and Permissions (Joomla ACL), the remaining tabs are:

• Rate limit & abuse protection — rate_enabled (Yes), rate_per_minute (10), rate_per_hour (80), trusted_proxies.
• FVTV Offered Services — persona fields plus notifications: notify_enabled (Yes), notify_email, notify_subject, webhook_type (none/slack/telegram/generic), webhook_url.
• Live Weather / Waves / Wind / Tides — weather_enabled (Yes), weather_lat (28.7367), weather_lon (-13.8675), weather_cache_ttl (30). Open-Meteo, no key.
• News Feed — news_enabled (Yes), rss_en/rss_it/rss_es, news_items (5), news_cache_ttl (30).
• Content Security Policy — csp_mode (off/report_only/enforce), csp_unsafe_inline, extra source lists, report URI.

Rate limiting is DB-atomic (per-IP minute+hour buckets on #__fvtvchatbot_rate; over-limit → HTTP 429). CSP keeps NVIDIA/Open-Meteo in connect-src, and the plugin sets standard security headers (X-Frame-Options, Referrer-Policy…) with replace=false.

Privacy and data handling

• Where data goes: messages to NVIDIA NIM; coordinates to Open-Meteo (if weather is on); news from your RSS URLs. Nothing else leaves the server.
• API key: encrypted at rest with libsodium, decrypted only at call time, sent server-to-server, redacted from logs.
• IP addresses: used only for rate limiting, never stored raw — the rate table keys on a truncated SHA-256, and notifications log a 32-char IP hash. Per-page context and admin knowledge are also tag-stripped and length-capped before reaching the model.
• Consent & persistence: a privacy-consent checkbox is shown before sending; set gdpr_text / gdpr_link for your footer notice. persist_conv is No by default (enable only if your cookie banner covers localStorage).

Updates and licence

Updates come through the FuerteventuraTV licensing gateway (com_gmclicenses), which registers the feed index.php?option=com_gmclicenses&task=api.update&format=raw&product=pkg_fvtvchatbot. Set the Download Key (Update Sites dlid or the Licence tab), then update via Extensions → Update → Find Updates → Update; never “Rebuild Update Sites”. Enforcement is soft: a definitive invalid/expired result suppresses the widget, returns HTTP 402 to chat and warns the admin; a transient gateway outage falls back to last-known-good.

Troubleshooting

FAQ

• Do I need my own NVIDIA key?

  Yes — a free nvapi- key from build.nvidia.com, pasted into Options → NVIDIA NIM API; stored encrypted and used server-side only.

• Which model should I choose?

  Default meta/llama-3.3-70b-instruct. A 70B model helps CS/SK/HR/RU; openai/gpt-oss-120b is highest quality but slowest; meta/llama-3.2-3b-instruct is fastest.

• Does every message cost NVIDIA credits?

  No — FAQ bypass answers cost zero credits, weather and news are cached (30 min), and before a key is set the bot uses a local fallback.

• Can I show it only on some pages?

  Yes — use show_on_routes (one route per line, /path/* for a prefix) and/or show_on_menu_item_ids; * means everywhere.

• How do off-offer notifications work?

  For an off-list request the model appends a hidden [[NOTIFY:reason]] tag; the server strips it and, if notify_enabled is on, sends an email and/or a Slack / Telegram / generic-JSON webhook and logs it.