Skip to content

J'AI Support Chat Module

The support_chat module provides an AI-powered customer support chatbot for the storefront. It leverages installed AI provider extensions (Claude, ChatGPT) to help customers find products, check order status, add items to their cart from handwritten notes, and optionally hand off to a live agent.

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.