Documentation
Overview: This document outlines the architecture, data structures, and key features
needed to implement a real-time chat application with a 3-panel UI:
1. Visitor List (Left Column)
2. Active Chat Window (Middle Column)
3. Visitor Profile + Chat History (Right Column)
1. UI Layout and Functional Breakdown
Panel 1: Visitor List (Left)
• Shows list of connected visitors.
• Displays visitor name, ID, and unread message counter (highlighted).
• Onclick: selects that visitor and opens chat in Panel 2.
Panel 2: Chat Window (Middle)
• Shows chat conversation with selected visitor.
• Aligns user and visitor messages on opposite sides.
• Appends new messages in real-time.
• Highlights new incoming messages temporarily.
Pane 3: Visitor Profile & Chat History (Right)
• Shows visitor details (name, IP, location, etc.).
• Lists last 5 chat sessions.
• On hover over each past chat: shows icons for:
o Chat Details
o Chat Summary
• Clicking an icon opens a modal with respective info.
2. Data Structures
A. Visitor Object
interface Visitor {
id: string;
name: string;
ip: string;
location: string;
avatarUrl?: string;
isOnline: boolean;
unreadCount: number;
lastActive: Date;
B. ChatMessage Object
interface ChatMessage {
id: string;
sender: 'visitor' | 'user';
content: string;
timestamp: Date;
isHighlighted?: boolean;
C. ChatSession Object
interface ChatSession {
sessionId: string;
visitorId: string;
messages: ChatMessage[];
startedAt: Date;
endedAt?: Date;
summary?: string;
}
D. UI State Object
interface ChatUIState {
selectedVisitorId: string | null;
visitorList: Visitor[];
chatSessions: Record<string, ChatSession>; // visitorId as key
3. Application Flow – Detailed Breakdown
This section explains the logical flow of the application across different user actions
and system events, ensuring smooth real-time chat functionality.
A. Initial Load
Purpose: Set up the chat environment with available data.
Steps:
1. Fetch All Connected Visitors
o On page load or agent login, make an API call or listen to a socket event
(like visitor_connected) to retrieve a list of currently connected visitors.
o Each visitor object includes details like ID, name, IP, status, etc.
2. Populate Visitor List in Left Panel
o Render the visitor list dynamically in the left column.
o Each visitor entry may also include their unread message count
(initialized to 0).
o Use this list to allow agents to select whom to chat with.
B. Selecting a Visitor
Purpose: To open and view chat messages from a specific visitor.
Steps:
1. Update Selected Visitor
o When the agent clicks on a visitor from the list, update a state variable like
selectedVisitorId.
o This ensures only one visitor is active at a time.
2. Load Active Chat Session
o Retrieve the chat session for the selected visitor (from memory, cache, or
API).
o Display this conversation in the middle pane.
o Reset the unread message counter for this visitor since the chat is now
active.
C. Incoming Message Handling (Real-Time)
Purpose: To handle messages as they arrive from visitors via WebSocket.
socket.on("new_message", (message) => {
const { visitorId } = message;
if (visitorId !== selectedVisitorId) {
// Visitor is not currently selected
incrementUnread(visitorId);
highlightMessage(visitorId);
} else {
// Visitor is selected, show the message immediately
addToChatSession(visitorId, message);
temporarilyHighlightMessage(message.id);
});
Explanation:
• When a new message arrives from a visitor:
o If the visitor is not currently selected, it:
▪ Increases that visitor’s unread count.
▪ Highlights their name in the left panel (e.g., bold text, red badge).
o If the visitor is selected, it:
▪ Instantly adds the message to the chat window.
▪ Temporarily highlights the message bubble for visibility (e.g.,
yellow background that fades after a few seconds).
D. Message Highlight Fade Out
Purpose: To make new messages visually stand out, but not permanently.
Two Options:
1. Using setTimeout()
o On receiving a new message, apply a highlighted CSS class.
o Use setTimeout() (e.g., 3–5 seconds) to remove the class and make the
message look like other normal messages.
temporarilyHighlightMessage(messageId) {
highlight(messageId); // Apply yellow background
setTimeout(() => removeHighlight(messageId), 3000);
2. Auto-Fade on User Reply
o As soon as the agent replies to that particular message thread:
▪ Remove the highlight instantly.
▪ This assumes the agent has addressed the message.
This ensures better UX by drawing attention to new messages but not cluttering the
interface.
E. Hover on Chat History (Right Panel)
Purpose: To give quick access to more detailed historical data.
Steps:
1. Display Chat Icons on Hover
o When the agent hovers over any previous chat session (within last 5),
show icons like:
2. Click to Open Modal
o On click of either icon, open a modal popup window.
o This modal fetches and displays:
▪ Chat Details: Full chat transcript, timestamps, agent names, etc.
▪ Chat Summary: Brief of chat intent, resolution status, sentiment
score (if available), etc.
Summary of Flow
Phase Trigger Result
Initial Load Page load / Agent login Load and display all connected visitors
Select Visitor User click on visitor Load chat + profile + reset unread
New Message Real-time socket event Update chat or increment unread
Message Highlight New message Highlight bubble and fade on timeout/reply
Hover on History Mouse enter Show detail & summary icons
Click Icon User click Open modal with relevant data
Conclusion
The architecture and data structures defined in this documentation address the
requirements of a scalable and responsive real-time chat application.
By dividing the chat interface into three clear and functional sections—visitor list, active
chat window, and visitor profile/history—we ensure an intuitive user experience for
support agents. Core features like real-time message handling, single chat focus,
message highlighting, and model-based chat details enable agents to respond faster and
more accurately.
