useShoppingAssistant

Overview

The useShoppingAssistant hook is the primary hook for interacting with the Shopping Assistant functionality. It provides access to conversation management, message sending, chat history, and all state related to the AI-powered shopping experience. This hook must be used within a component that is wrapped by the UnbxdShoppingAssistantWrapper.

⚠️

Important:

The useShoppingAssistant hook must be used within a component that is wrapped by UnbxdShoppingAssistantWrapper. Using it outside this context will result in an error.

Usage

import { useShoppingAssistant } from "@unbxd-ui/react-shopping-assistant-hooks";

Code Example

const AIAssistant = () => {
    const {
        startConversation,
        askAgent,
        resetChat,
        fetchHistory,
        fetchAllConversations,
        updateConversationId,
        chat,
        conversationId,
        conversationsList,
        loading,
        initialLoading
    } = useShoppingAssistant();
    
    return (
        <div>
            {/* Your Shopping Assistant UI */}
        </div>
    );
};

Hook API

Return Values

conversationId

string

The ID of the current active conversation.

const { conversationId } = useShoppingAssistant();
 
// Check if conversation is active
if (conversationId) {
    console.log("Active conversation:", conversationId);
}

conversation

Array

Array of chat messages in the current conversation. Each message has a role (user/assistant), message and content.

Conversation Structure:

[
   // User message
    {
        role: "user",
        message: "Show me laptops"
    },
    // Assistant message
    {
        role: "assistant", 
        message: "Here are some great laptops for you",
        content: {
            filters: [...],  // Available filters
            products: [...]  // Product recommendations
        }
    } 
]

Usage:

const { conversation } = useShoppingAssistant();
 
return (
    <div>
        {conversation.map((message, index) => (
            <div key={index} className={`message ${message.role}`}>
                <strong>{message.role}:</strong> {message.message}
                {message.content?.products && (
                    <div>Found {message.content.products.length} products</div>
                )}
            </div>
        ))}
    </div>
);

conversationsList

function

Array of all conversations for the current user.

const { conversationsList, updateConversationId } = useShoppingAssistant();
 
// Render conversations list
return (
    <div>
        {conversationsList.map(conversation => (
            <button 
                key={conversation.id}
                onClick={() => updateConversationId(conversation.id)}
            >
                {conversation.title || `Conversation ${conversation.id}`}
            </button>
        ))}
    </div>
);

loading

boolean

Indicates whether a message is currently being sent/processed.

const { loading, askAgent } = useShoppingAssistant();
 
return (
    <div>
        <button 
            onClick={() => askAgent("Help me find shoes")}
            disabled={loading}
        >
            {loading ? "Sending..." : "Send Message"}
        </button>
    </div>
);

initialLoading

boolean

Indicates whether the app is loading (initializing conversation or fetching history).

const { initialLoading, chat } = useShoppingAssistant();
 
if (initialLoading) {
    return <div>Loading conversation...</div>;
}
 
return (
    <div>
        {/* Render chat interface */}
        {chat.map(message => (...))}
    </div>
);

startConversation

function

Initializes a new conversation with the Shopping Assistant API. This function is automatically called when the wrapper loads if no existing conversation is found.

const { startConversation } = useShoppingAssistant();
 
// Start a new conversation
const startNewConversation = async () => {
    await startConversation();
};

Behavior:

Creates a new conversation ID via API call
Stores the conversation ID in localStorage or sessionStorage based on wrapper configuration
Updates the conversation state

askAgent

function

Sends a message to the Shopping Assistant AI and receives a response.

Parameters:

message string - The user's message to send to the AI
filters object (optional) - Additional filters to apply to the search
metadata object (optional) - Additional metadata to include with the request

const { askAgent } = useShoppingAssistant();
 
// Basic message
askAgent("Show me laptops under $1000");
 
// Message with filters
askAgent("Find running shoes", {
    brand: "nike",
    size: "10"
});
 
// Message with metadata
askAgent("What's trending?", null, {
    source: "homepage",
    timestamp: Date.now()
});

Behavior:

Adds user message to chat history immediately.
Sets corresponding loading state.
Sends API request with message, filters, and metadata.
Adds AI response to chat history when received.

fetchHistory

function

Fetches the chat history for a specific conversation ID.

Parameters:

conversationId string - The ID of the conversation to fetch

const { fetchHistory } = useShoppingAssistant();
 
// Load a specific conversation
const loadConversation = (id) => {
    fetchHistory(id);
};

Behavior:

Sets app corresponding loading state.
Fetches conversation history from API.
Replaces current chat with fetched history.

fetchAllConversations

function

Fetches all conversations for the current user.

const { fetchAllConversations, conversationsList } = useShoppingAssistant();
 
// Load all user conversations
useEffect(() => {
    fetchAllConversations();
}, []);
 
// Display conversations list
conversationsList.map(conversation => (
    <div key={conversation.id}>{conversation.title}</div>
));

updateConversationId

function

Updates the current conversation ID in the state and stores it in localStorage/sessionStorage according to the wrapper configurations.

Parameters:

conversationId string - The new conversation ID to set

const { updateConversationId } = useShoppingAssistant();
 
// Switch to a different conversation
const switchConversation = (newId) => {
    updateConversationId(newId);
};

ResetChat