Skip to content

J'AI Support Chat (Extension)

J'AI was promoted from a core module to an extension (ext_jai_chat) in 2026-05. The support_chat namespace remains as a thin set of strategy ABCs (OrderLookupStrategy, LiveAgentStrategy); the resolvers, services, models, and admin UI all live in the extension. Installing or uninstalling J'AI is now per-channel via ChannelExtension.

If no chat extension is installed:

  • The storefront widget is hidden
  • The admin "Support Chat" page renders a "no provider installed" placeholder
  • chatSettings.enabled returns false

The extension contributes via register_strategy, register_admin_page_tab, register_query/register_mutation, and a jai-session-cleanup Temporal schedule. See Building Extensions for the contributed slots.

The rest of this page documents the strategy contract and the GraphQL surface the extension exposes — both unchanged from the previous module-based implementation.

Architecture

The module is stateless per-request. Conversation history is maintained on the frontend in sessionStorage and sent with each request.

Storefront Widget (JaiChat.svelte)
  ↓ POST /api/chat (BFF proxy)
  ↓ GraphQL: sendChatMessage mutation
  ↓ ChatService.process_message()
  ↓ AICompletionStrategy (ext_claude / ext_chatgpt)
  ↓ Parse response → execute actions (product search, order lookup, cart add)
  ↓ Return ChatResponse with message + action cards

Backend Files

File Purpose
modules/support_chat/strategies.py OrderLookupStrategy and LiveAgentStrategy ABCs
modules/support_chat/local_order_lookup.py Built-in order lookup using local Order model
modules/support_chat/services.py ChatService — core orchestrator
modules/support_chat/types.py Strawberry GraphQL types
modules/support_chat/resolvers.py GraphQL queries and mutations

Strategy ABCs

OrderLookupStrategy

Extension point for ERP order status lookups. Methods:

  • lookup_order(order_number, email?) → OrderStatusResult
  • get_tracking(order_number) → OrderStatusResult

The built-in LocalOrderLookupStrategy queries the local Order table. An ERP extension registers its own implementation to override.

LiveAgentStrategy

Extension point for live chat handoff. Methods:

  • is_available() → bool
  • initiate_handoff(session_id, context?) → HandoffResult

No built-in implementation. Only activates when an extension (Zendesk, Intercom, Freshdesk, etc.) is installed.

GraphQL API

Queries

  • chatSettings — Returns enabled status, terms text, disclaimers, welcome message, live agent availability. No auth required.
  • chatOrderStatus(orderNumber, email?) — Direct order status lookup outside of chat flow.

Mutations

  • sendChatMessage(messages: [ChatMessageInput!]!, imageUrl: String) — Main chat interaction. Returns ChatResponse with message text and action cards.
  • requestLiveAgent(sessionContext: String) — Initiates handoff to a live agent if a LiveAgentStrategy is registered.

Settings

All settings are stored in the Setting table with module="support_chat" (Decided #21):

Key Type Purpose
support_chat_enabled boolean Master toggle
support_chat_terms_text string T&C users must accept
support_chat_disclaimer_top string Top warning banner
support_chat_disclaimer_bottom string Bottom disclaimer
support_chat_welcome_message string Initial greeting
support_chat_ai_provider string AI provider name or "auto"
support_chat_system_prompt_override string Custom prompt additions

Action Types

The AI response is parsed for structured action blocks. Supported types:

Action Type Description
product_recommendation Product search results with cards
order_status Order status + tracking info card
add_to_cart Button to add a specific variant
live_agent_offer Prompt to connect with a live agent

Image Upload (Handwritten Notes)

  1. Customer uploads an image via the chat widget
  2. Image goes through the existing /api/upload BFF endpoint
  3. URL is passed to sendChatMessage as imageUrl
  4. The AI provider (Claude vision / GPT-4o) reads the handwritten items
  5. AI responds with product search actions for each item

Extending J'AI

ERP Order Lookup Extension

# ext_erp_order_lookup/strategy.py
from vectis.modules.support_chat.strategies import OrderLookupStrategy, OrderStatusResult

class ERPOrderLookupStrategy(OrderLookupStrategy):
    @property
    def provider_name(self) -> str:
        return "erp"

    async def lookup_order(self, order_number, email=None):
        # Call ERP API via httpx
        ...

    async def get_tracking(self, order_number):
        # Call ERP tracking API
        ...

Register in on_activate: 

strategy_resolver.register(
    OrderLookupStrategy, ERPOrderLookupStrategy(...),
    name="erp", extension_name=self.name,
)

Live Agent Extension

Same pattern using LiveAgentStrategy. When registered, the storefront widget automatically shows a "Talk to a person" button.

Admin Settings Page

Located at /settings/support-chat/ in the admin. Allows configuring:

  • Enable/disable toggle
  • Terms & conditions text
  • Top and bottom disclaimer messages
  • Welcome message
  • AI provider selection
  • System prompt override

The page is linked from the main Settings hub.