useChatContext Hook

Status: Coming Soon - This hook is planned for Phase 2 of the SDK development.

Overview

The useChatContext hook (planned for a future release) will allow you to update the chat assistant with contextual information about the current page and user session. This context will be automatically included when sending messages, enabling the AI to provide more relevant and intelligent responses.

Planned Usage

When implemented, you'll use the hook like this:

import { useChatContext } from '@cyborg-sdk/react';

function Dashboard() {
  // Update the chat context with page and session data
  useChatContext({
    pageData: {
      currentPage: '/dashboard',
      description: 'User dashboard showing account overview, recent activity, and quick actions.',
      widgets: ['account-summary', 'recent-orders', 'quick-actions'],
    },
    sessionData: {
      userId: 'user123',
      subscriptionTier: 'premium',
      recentActivity: ['viewed-product-X'],
    }
  });

  return (
    <div className="dashboard">
      {/* Dashboard content */}
    </div>
  );
}

Planned API

Parameters

interface ChatContextUpdate {
  pageData?: {
    currentPage: string;           // Current route/path (e.g., '/dashboard')
    description: string;           // What the page does
    [key: string]: unknown;        // Any page-specific structured data
  };
  sessionData?: {
    userId?: string;               // Current user ID
    [key: string]: unknown;        // Any user/session-specific data
  };
}

Planned Features

1. Page Context

Automatically provide information about what page the user is currently on:

useChatContext({
  pageData: {
    currentPage: '/products/laptops',
    description: 'Product listing page showing laptops with filtering and sorting options',
    filters: ['brand', 'price', 'processor'],
    displayMode: 'grid',
  },
});

2. Session Context

Include user and session information that the AI can use:

useChatContext({
  sessionData: {
    userId: 'user123',
    subscriptionTier: 'premium',
    accountCreatedDate: '2024-01-15',
    recentActivity: ['viewed-product', 'added-to-cart', 'checkout-started'],
  },
});

3. Automatic System Prompt Enhancement

The context will be automatically added to the AI's system prompt when you send messages:

System: You are a helpful assistant. The user is currently on:
- Page: /dashboard
- Description: User dashboard showing account overview
- User ID: user123
- Subscription: premium

User: How do I export my data?
Assistant: Since you're on the dashboard with a premium subscription, you can...

Planned Examples

Multi-Page Application

// Dashboard.tsx
import { useChatContext } from '@cyborg-sdk/react';

function Dashboard() {
  useChatContext({
    pageData: {
      currentPage: '/dashboard',
      description: 'Main dashboard with account overview and quick actions',
      metrics: ['revenue', 'orders', 'customers'],
    },
  });

  return <div>{/* Dashboard content */}</div>;
}

// Products.tsx
function Products() {
  useChatContext({
    pageData: {
      currentPage: '/products',
      description: 'Product catalog with search, filtering, and sorting',
      itemCount: 1200,
      categories: ['Electronics', 'Clothing', 'Books'],
    },
  });

  return <div>{/* Products content */}</div>;
}

// Checkout.tsx
function Checkout() {
  useChatContext({
    pageData: {
      currentPage: '/checkout',
      description: 'Checkout flow for completing purchase',
      step: 'shipping',
    },
    sessionData: {
      userId: 'user123',
      cartValue: 299.99,
      itemCount: 3,
    },
  });

  return <div>{/* Checkout content */}</div>;
}

E-Commerce Product Page

function ProductDetail({ productId }) {
  const [product, setProduct] = useState(null);

  useChatContext({
    pageData: {
      currentPage: `/products/${productId}`,
      description: `Product detail page for ${product?.name}`,
      productId,
      productName: product?.name,
      category: product?.category,
      price: product?.price,
      inStock: product?.inStock,
    },
    sessionData: {
      userId: 'user123',
      viewedSimilarProducts: [/* related product IDs */],
    },
  });

  return <div>{/* Product details */}</div>;
}

Settings Page with User Info

function Settings() {
  const { user } = useAuth();

  useChatContext({
    pageData: {
      currentPage: '/settings',
      description: 'User account settings and preferences',
      sections: ['profile', 'notifications', 'privacy', 'billing'],
    },
    sessionData: {
      userId: user.id,
      email: user.email,
      accountType: user.accountType,
      lastLogin: user.lastLogin,
    },
  });

  return <div>{/* Settings content */}</div>;
}

Planned Benefits

1. Context-Aware Responses

The AI will understand what page users are on and provide relevant help:

• On Dashboard: Suggest analyzing metrics, exporting data, updating goals
• On Products: Help with filtering, searching, comparing items
• On Checkout: Assist with payment issues, shipping questions, promo codes

2. Personalized Assistance

User context enables personalized responses:

User (Premium tier) on Products page: "Can I bulk export my product list?"
Assistant: "Yes! As a premium subscriber, you can export your entire
product catalog as CSV or JSON in the settings."

User (Free tier) on Products page: "Can I bulk export my product list?"
Assistant: "Bulk export is available with our Premium plan. You can
upgrade or export items individually."

3. Workflow Continuity

The AI understands multi-step processes:

User on Checkout page: "I'm getting a payment error"
Assistant: "I see you're in checkout with 3 items. The payment error
could be due to [common checkout issues]. Try..."

Implementation Status

• [ ] Hook implementation
• [ ] Context state management
• [ ] System prompt enrichment
• [ ] API integration with context data
• [ ] Testing and documentation
• [ ] Release in Phase 2

Timeline

The useChatContext hook is planned for Phase 2 of the SDK. Check back for updates on this feature.

Related Documentation

• ChatProvider - Main provider component
• useChat Hook - Access chat state and methods
• Configuration - Configure the SDK