Chat Sessions

​

Overview

​

GET /api/user/chat/:sessionId

​

Authentication

​

URL Parameters

​

Response

​

Response Example

{
  "_id": "507f1f77bcf86cd799439011",
  "messages": [
    {
      "role": "user",
      "content": "What should I focus on studying next?"
    },
    {
      "role": "assistant",
      "content": "Based on your recent quiz results, I recommend focusing on the authentication module in your Web Development course. You scored 60% on that chapter, which indicates it needs review."
    },
    {
      "role": "user",
      "content": "Can you explain JWT tokens?"
    },
    {
      "role": "assistant",
      "content": "JWT (JSON Web Token) is a compact, URL-safe means of representing claims between two parties. It consists of three parts: Header, Payload, and Signature, separated by dots. JWTs are commonly used for authentication because they're stateless and can be verified without querying a database."
    }
  ]
}

​

Error Responses

{
  "success": false,
  "message": "Chat session not found"
}

​

Implementation Notes

• Uses MongoDB aggregation pipeline for efficient retrieval
• Matches both sessionId and userId to ensure security
• Returns only _id and messages fields (excludes metadata)
• System messages (from context building) are included in the response

​

DELETE /api/user/chat/:sessionId

​

Authentication

​

URL Parameters

​

Response

​

Response Example

{
  "success": true,
  "message": "Chat deleted successfully"
}

​

Error Responses

{
  "success": false,
  "message": "Missing sessionId"
}

​

Implementation Notes

• Uses findOneAndDelete with both sessionId and userId for security
• Permanently removes the session and all associated messages
• Returns 404 if the session doesn’t exist or doesn’t belong to the user
• Cannot be undone - ensure user confirmation before deletion

​

POST /api/user/previous-chats

​

Authentication

​

Request Body

​

Response

​

Response Example

{
  "chats": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "sessionId": "a3f2c1b0-4e5d-6f7g-8h9i-0j1k2l3m4n5o",
      "messages": "How do I implement authentication in Express?",
      "updatedAt": "Mon Mar 04 2026"
    },
    {
      "_id": "507f191e810c19729de860ea",
      "sessionId": "b4g3d2c1-5f6e-7g8h-9i0j-1k2l3m4n5o6p",
      "messages": "What should I focus on studying next?",
      "updatedAt": "Sun Mar 03 2026"
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "sessionId": "c5h4e3d2-6g7f-8h9i-0j1k-2l3m4n5o6p7q",
      "messages": "Explain React hooks",
      "updatedAt": "Sat Mar 02 2026"
    }
  ]
}

​

Error Responses

{
  "success": false,
  "message": "Error while fetching conversations"
}

​

Implementation Notes

• Retrieves all sessions for the authenticated user
• Selects only sessionId, messages, and updatedAt fields
• Returns chats in reverse order (most recent first)
• Uses the first message content as a preview/summary
• Date is formatted using JavaScript’s toDateString() method
• Empty array is returned if user has no chat sessions

​

Data Model

​

ChatSession Schema

{
  userId: String,              // Reference to User model
  sessionId: String,            // UUID v4 identifier
  messages: [
    {
      role: String,             // 'user', 'assistant', or 'system'
      content: String           // Message text
    }
  ],
  createdAt: Date,              // Auto-generated timestamp
  updatedAt: Date               // Auto-updated timestamp
}

​

Indexes

• Composite index on (userId, sessionId) for efficient lookups
• Sessions are user-scoped for security and privacy

​

Usage Patterns

​

Building a Chat History UI

1. List View: Use POST /api/user/previous-chats to display all conversations
   • Show the first message as the conversation title
   • Display the updatedAt timestamp
   • Use sessionId as the navigation key
2. Detail View: Use GET /api/user/chat/:sessionId to show full conversation
   • Render all messages in chronological order
   • Filter out system role messages if desired (they’re internal context)
3. Deletion: Use DELETE /api/user/chat/:sessionId with user confirmation
   • Show a confirmation dialog before deletion
   • Redirect to chat list after successful deletion

​

Continuing a Conversation

1. Get the sessionId from the chat list or URL
2. Make a new POST /api/user/ai-chat request with the sessionId in the body
3. The AI will load the last 20 messages from the session for context
4. The response includes the updated conversation history

​

Session Lifecycle

1. Creation: Sessions are created automatically when a user sends their first message without a sessionId
2. Updates: Sessions are updated each time a message is sent (user) or received (assistant)
3. Persistence: Sessions persist indefinitely until explicitly deleted
4. Security: Sessions are always filtered by userId to prevent cross-user access

​

Best Practices

1. Pagination: For users with many chats, implement client-side pagination
2. Caching: Cache the chat list and individual sessions to reduce API calls
3. Optimistic UI: Update the UI immediately when sending messages, then sync with the server response
4. Error Handling: Always handle 404 errors gracefully (session may have been deleted)
5. Confirmation: Require explicit user confirmation before deleting sessions

​

Security

• All endpoints require authentication via JWT token
• Sessions are strictly user-scoped (userId is always matched)
• Attempting to access another user’s session returns 404 (not 403) to avoid information leakage
• Session IDs are UUIDs, making them difficult to guess

​

Performance Considerations

• The chat list endpoint fetches all user sessions - consider pagination for power users
• Individual session retrieval uses MongoDB aggregation for efficiency
• Messages are not paginated within a session - very long sessions may cause performance issues
• Consider implementing a message limit per session (e.g., 1000 messages)

​

Related Endpoints

• AI Chatbot - Send messages and create new sessions
• Learning Roadmaps - AI-generated learning paths