Skip to content

J'AI Chat

J'AI Chat — conversational support assistant with order lookup, tracking, and live-agent handoff. AI provider selected from any installed AI extension (ChatGPT, Claude, Grok). The extension is fully self-contained: the chat widget renders on every storefront page, answers are generated through whichever AICompletionStrategy is registered, and the assistant can search the catalog, add items to the cart, look up order status, and offer a live-agent handoff — all logged to its own chat_logs table.

At a glance
Extension id jai_chat
Category communication
Version 0.1.0
Provides Storefront chat GraphQL API, ChatLog model + migrations, order-lookup / live-agent strategy ABCs, privacy exporter, admin settings page
External account None (uses installed AI provider extensions)

What It Provides

  • GraphQL surface — SupportChatQuery and SupportChatMutation contributed to the composed schema via the graphql_queries() / graphql_mutations() surfaces: queries chatSettings (storefront-facing, no auth required) and chatOrderStatus; mutations sendChatMessage and requestLiveAgent.
  • Model + migrations — the ChatLog model (chat_logs table) registered via the models() surface, with its own per-extension migration chain (jai0001initial).
  • Strategy ABCs — OrderLookupStrategy and LiveAgentStrategy, the plug-in points that ERP and live-agent provider extensions implement. on_activate registers the built-in LocalOrderLookupStrategy (name local), which queries the local Order table.
  • Privacy exporter — chat conversations ride the GDPR subject-access export bundle as the support_chat section, matched by user id or the chat log's recorded user email.
  • Admin surface — a Settings-section nav item and an admin_settings_pages deep link, both to /settings/support-chat.
  • Storefront widget — JaiChat.svelte is rendered from the storefront root layout with the chatSettings payload.

See J'AI Support Chat for the architecture walkthrough and Building Extensions for the contributed slots.

Setup

  1. Enable the extension for a channel under Settings > Extensions; the Configure action navigates to Settings > J'AI Chat (/settings/support-chat).
  2. Install and configure at least one AI provider extension (ChatGPT, Claude, or Grok). Chat replies need a registered AI completion strategy — with none available, the bot answers with a fixed "unable to process your request" apology.
  3. On Settings > J'AI Chat, set the terms text, top/bottom disclaimers, welcome message, AI provider (auto or a specific provider), and an optional system prompt override.
  4. The chat widget appears on the storefront automatically; its enabled flag, terms, and disclaimers come from the chatSettings query.

Configuration Reference

The manifest deliberately has no config_schema — configuration lives on the extension's own settings page at /settings/support-chat, persisted as support_chat_* keys (module support_chat) in the platform Setting table. The keys and their code defaults:

Setting key Default Purpose
support_chat_enabled true Master on/off flag returned to the storefront widget.
support_chat_terms_text Built-in AI-disclaimer text Terms the customer must accept before chatting.
support_chat_disclaimer_top "You are chatting with J'AI, an AI assistant." Banner above the conversation.
support_chat_disclaimer_bottom "AI responses may be inaccurate. Verify important details." Banner below the conversation.
support_chat_welcome_message Built-in greeting First message shown to the customer.
support_chat_ai_provider auto AI provider name, or auto to use any registered provider.
support_chat_system_prompt_override (empty) Appended to the built-in system prompt as "Additional instructions" — it does not replace it.

Permissions

  • support.view_logs
  • support.manage_settings

Manifest permissions are upserted at boot but belong to no role yet — role assignment is currently a manual step.

Operational Notes

  • Every exchange is logged — each user message/AI response pair is persisted to chat_logs with session id, AI provider used, actions requested/executed, optional image URL, and the user's id/email/channel when known. Logged conversations are personal data: they are included in the privacy subject-access export (section support_chat).
  • Action tags drive commerce behavior — the AI is prompted to emit [ACTION type="..."] tags which the service parses and executes server-side: product_search (optionally with auto_add and quantity, which adds matched variants to the cart), order_lookup, add_to_cart, and live_agent_request. Product search only matches products in published/active status and active variants, progressively shortening the query to split product name from variant hint.
  • Order lookup verifies email when given — if the customer supplies an email, it must match the order's email or the lookup reports "not found" rather than leaking order details. Lookup prefers a registered OrderLookupStrategy (built-in local queries the Vectis Order table) and falls back to a direct local query.
  • Live agent is inert until an extension provides it — there is no built-in LiveAgentStrategy implementation; chatSettings.liveAgentAvailable stays false and requestLiveAgent returns "Live agent support is not currently available" unless a provider extension registers one.
  • Generation parameters — chat replies are generated with max_tokens=2048, temperature=0.4; the bot name is fixed to J'AI in chatSettings.
  • Image attachments are referenced, not vision-analyzed — sendChatMessage accepts an optional image_url, which is appended to the prompt text as an uploaded-image note and stored on the chat log.
  • Grandfathered table name — chat_logs predates the ext_<name>_ table-prefix convention and is explicitly grandfathered; on databases that ran the core migration chain, the extension's initial revision is stamped rather than executed. See Per-Extension Migrations.