Files

T

morteza-mortezai 9a8515d7ab chat

2025-11-30 11:52:38 +03:30

11 KiB

Raw Blame History

Frontend WebSocket Chatbot Implementation Prompt

Create a modern, responsive frontend application for a real-time chatbot system using Socket.IO. The chatbot is designed for an Electrical Power Panels (تابلو برق) e-commerce platform that provides product guidance in Persian/Farsi.

Technical Requirements

1. WebSocket Connection Setup

Connection Path: /ws-chatbot
Library: Use Socket.IO client library (socket.io-client)
Connection Options:
- Support both authenticated (with JWT token) and anonymous connections
- Token can be provided via:
  - Query parameter: ?token=YOUR_JWT_TOKEN
  - Authorization header: Authorization: Bearer YOUR_JWT_TOKEN
- For anonymous users, the system uses a ULID stored in cookies (chatbot_session_id)
- CORS is enabled with credentials support

2. WebSocket Events to Implement

Connection Events

connect - Socket connected successfully
disconnect - Socket disconnected
connection_failed - Connection failed

Authentication Events

Emit: authenticate (if using token-based auth)

Listen: authenticated - Authentication successful

{
  "message": "authenticated",
  "userId": "user_id",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Listen: unauthorized - Authentication failed

{
  "message": "error_message",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Session Management Events

Emit: create_session - Create a new chat session

Listen: session_created - Session created successfully

{
  "status": "success",
  "data": {
    "id": "session_ulid",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "lastMessageAt": "2024-01-01T00:00:00.000Z",
    "messages": []
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Emit: join_chat - Join an existing chat session (pass sessionId as string)

Listen: chat_joined - Successfully joined chat session

{
  "status": "success",
  "data": {
    "id": "session_ulid",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "lastMessageAt": "2024-01-01T00:00:00.000Z",
    "messages": [
      {
        "id": "message_ulid",
        "content": "message content",
        "type": "user" | "bot" | "system",
        "status": "sent" | "delivered" | "read" | "failed",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "responseToId": "optional_message_id",
        "metadata": {},
        "tokensUsed": 0
      }
    ]
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Emit: leave_chat - Leave a chat session (pass sessionId as string)
Listen: chat_left - Successfully left chat session

Message Events

Emit: send_message - Send a regular message

{
  "content": "user message text",
  "sessionId": "session_ulid",
  "responseToId": "optional_message_id_to_reply_to",
  "metadata": {}
}

Emit: send_message_stream - Send a message and receive streaming response

{
  "content": "user message text",
  "sessionId": "session_ulid",
  "responseToId": "optional_message_id_to_reply_to",
  "metadata": {}
}

Listen: message_received - User message received and saved

{
  "status": "success",
  "data": {
    "id": "message_ulid",
    "content": "message content",
    "type": "user",
    "status": "sent",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "responseToId": null,
    "metadata": {},
    "tokensUsed": 0
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Streaming Response Events (for `send_message_stream`)

Listen: bot_response_start - Bot started generating response

{
  "status": "success",
  "data": {
    "userMessageId": "message_ulid"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Listen: bot_response_chunk - Receive a chunk of bot response (streaming)

{
  "status": "success",
  "data": {
    "chunk": "partial text chunk",
    "userMessageId": "message_ulid"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Listen: bot_response_end - Bot finished generating response

{
  "status": "success",
  "data": {
    "userMessageId": "message_ulid",
    "fullResponse": "complete bot response text"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Non-Streaming Bot Response (for `send_message`)

Listen: bot_response - Complete bot response received

{
  "status": "success",
  "data": {
    "id": "message_ulid",
    "content": "complete bot response",
    "type": "bot",
    "status": "sent",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "responseToId": "user_message_ulid",
    "metadata": {
      "confidence": 0.95,
      "sources": [],
      "llmContext": {}
    },
    "tokensUsed": 150
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Typing Indicators

Emit: typing_start - User started typing (pass sessionId as string)
Emit: typing_stop - User stopped typing (pass sessionId as string)
Listen: typing_start - Another user started typing
Listen: typing_stop - Another user stopped typing

User Presence Events

Listen: user_joined - Another user joined the session
Listen: user_left - Another user left the session

Error Events

Listen: error - General error
Listen: websocket_error - WebSocket connection error
Listen: session_error - Session-related error
Listen: message_error - Message-related error

All error events follow this format:

{
  "status": "error",
  "message": "error message",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

3. REST API Endpoints (Optional - for session management)

The backend also provides REST endpoints that can be used for session management:

POST /chatbot/sessions - Create a new chat session
GET /chatbot/sessions?limit=10 - Get user's chat sessions (paginated)
GET /chatbot/sessions/:sessionId - Get a specific chat session with messages
POST /chatbot/messages - Send a message (non-streaming)
POST /chatbot/messages/stream - Send a message and get Server-Sent Events (SSE) streaming
PUT /chatbot/sessions/:sessionId/close - Close a chat session
PUT /chatbot/sessions/:sessionId/messages/read - Mark messages as read

4. UI/UX Requirements

Design

Modern, clean, and responsive design
Support for Persian/Farsi (RTL) text direction
Mobile-first approach with desktop support
Dark mode support (optional but recommended)
Smooth animations and transitions

Chat Interface Components

Session List Sidebar (optional)
- List of all chat sessions
- Show last message preview
- Show unread message count
- Show session status (active/closed)
- Create new session button
Chat Window
- Message list with scroll-to-bottom functionality
- Message bubbles:
  - User messages: Right-aligned (or left in RTL), distinct styling
  - Bot messages: Left-aligned (or right in RTL), distinct styling
  - System messages: Centered, muted styling
- Show message timestamps (relative or absolute)
- Show message status indicators (sent, delivered, read, failed)
- Support for message replies (if responseToId is provided)
- Markdown rendering for bot messages (if applicable)
- Copy message functionality
Input Area
- Text input field with character counter (max 2000 characters)
- Send button
- Support for Enter key to send (Shift+Enter for new line)
- Typing indicator display
- File upload support (if needed in future)
- Emoji picker (optional)
Streaming Response Display
- Show typing indicator when bot_response_start is received
- Display streaming text character-by-character or word-by-word as chunks arrive
- Smooth animation for streaming text
- Show completion when bot_response_end is received
- Handle errors gracefully during streaming
Connection Status
- Visual indicator for connection status (connected/disconnected/reconnecting)
- Auto-reconnect functionality with exponential backoff
- Show connection errors to user
Error Handling
- Display user-friendly error messages
- Retry mechanisms for failed operations
- Toast notifications for errors
- Persian/Farsi error messages

Features

Real-time Updates: All messages should appear in real-time
Message Persistence: Load previous messages when joining a session
Auto-scroll: Automatically scroll to bottom when new messages arrive
Typing Indicators: Show when bot is generating response
Message Status: Display sent/delivered/read status for user messages
Session Management: Create, join, leave, and close sessions
Responsive Design: Works on mobile, tablet, and desktop
Accessibility: WCAG 2.1 AA compliance
Performance: Optimize for smooth scrolling with many messages (virtual scrolling if needed)

5. State Management

Implement proper state management for:

WebSocket connection state
Current active session
Message list for current session
Session list
Typing indicators
Connection status
Error states

6. Technical Stack Recommendations

Framework: React, Vue, or Angular (your choice)
State Management: Redux, Zustand, Pinia, or Context API
WebSocket: socket.io-client
Styling: Tailwind CSS, Material-UI, or styled-components
Icons: React Icons, Heroicons, or similar
Date Formatting: date-fns or moment.js
HTTP Client: Axios or fetch API
Build Tool: Vite, Create React App, or Next.js

7. Implementation Notes

Handle reconnection automatically
Store ULID in cookies for anonymous users
Implement proper cleanup on component unmount
Debounce typing indicators (send typing_stop after 3 seconds of inactivity)
Implement message queuing for offline scenarios
Add loading states for all async operations
Implement proper error boundaries
Add analytics/tracking (optional)
Support for keyboard shortcuts (optional)

8. Testing Requirements

Unit tests for WebSocket event handlers
Integration tests for message flow
E2E tests for critical user flows
Test reconnection scenarios
Test error handling
Test streaming response display

9. Additional Features (Optional)

Message search within a session
Export chat history
Share session link
Voice input (speech-to-text)
Message reactions
Rich text formatting in messages
Product cards/embeds in bot responses
Quick reply buttons

10. Example Flow

User opens the application
Application connects to WebSocket (/ws-chatbot)
If authenticated, token is sent; otherwise, ULID is used from cookie or generated
User creates a new session or joins an existing one
Previous messages are loaded and displayed
User types a message and sends it
Message appears immediately in the chat
Bot response starts streaming (if using streaming) or arrives as complete message
User can continue the conversation
Connection is maintained and auto-reconnects if dropped

Deliverables

Create a complete, production-ready frontend application with:

Clean, maintainable code structure
Comprehensive error handling
Responsive design
Real-time WebSocket integration
TypeScript support (recommended)
Documentation and comments
README with setup instructions

11 KiB Raw Blame History