Live Chat API

A comprehensive real-time chat API with WebSocket support and full CRM capabilities for customer support and relationship management.

Features

Real-Time Communication

• WebSocket API: Bi-directional real-time communication
• Instant Messaging: Send and receive messages in real-time
• File Attachments: Secure file upload with presigned URLs and CloudFront CDN
• Typing Indicators: Show when users are typing
• Connection Management: Automatic connection tracking and cleanup
• Unread Count Tracking: Automatically tracks unread customer messages for agents
• Auto-Provisioning: Automatic customer and conversation creation on connect

CRM Features

• Customer Management: Complete customer profile management with custom fields
• Customer Segmentation: Tag and categorize customers
• Customer History: Track all conversations and interactions
• Customer Status: Active/blocked customer management

Conversation Management

• Multi-Channel Support: Web, mobile, and email channels
• Priority Levels: Low, medium, high, and urgent priorities
• Conversation Status: Open, pending, closed, and archived states
• Conversation Assignment: Assign conversations to specific agents
• Satisfaction Ratings: Collect post-conversation feedback (1-5 stars)
• Conversation Tags: Categorize and organize conversations
• Message History: Full conversation history and search
• Unread Count Management:
  • Tracks the number of unread customer messages per conversation
  • Automatically increments when customers send messages
  • Automatically resets to 0 when an agent connects to the conversation or sends a message
  • Helps agents prioritize conversations that need attention

Agent Management

• Agent Profiles: Manage agent information and skills
• Availability Status: Online, offline, away, and busy states
• Capacity Management: Set maximum concurrent conversations per agent
• Smart Assignment: Automatically assign to agents with available capacity
• Agent Skills: Tag agents with specific skills for routing
• Activity Tracking: Automatic agent activity monitoring with idle timeout
• Intelligent Routing: Routes to human agents when available, falls back to AI chatbot when no agents are online
• Auto Status Management: Automatically marks idle agents as "away" after 5 minutes of inactivity

AI-Powered Features

• Knowledge Base Integration: AI chatbot with RAG (Retrieval-Augmented Generation)
• Smart Agent Routing: Only uses AI when no human agents are available
• Context-Aware Responses: AI maintains conversation context
• Fallback Messages: Graceful handling when knowledge base has no relevant content

Analytics & Reporting

• Message Statistics: Track message counts and activity
• Conversation Metrics: Monitor conversation volumes and response times
• Agent Performance: Track agent workload and availability

Architecture

Technology Stack

• API Gateway WebSocket: For real-time bidirectional communication
• API Gateway HTTP: For REST API endpoints
• AWS Lambda: Serverless compute for all functions
• DynamoDB: NoSQL database for all data storage
• S3: Object storage for file attachments
• CloudFront: CDN for serving attachments globally
• SST (Serverless Stack): Infrastructure as code framework
• TypeScript: Type-safe development

Database Tables

Connections Table

• Tracks active WebSocket connections
• Indexed by user ID and conversation ID
• TTL enabled for automatic cleanup

Messages Table

• Stores all chat messages
• Indexed by conversation ID and sender ID
• Supports text, image, file, and system messages

Customers Table

• Customer profile information
• Custom fields support for additional data
• Indexed by email, company, and status

Conversations Table

• Conversation metadata and status
• Indexed by customer, agent, status, and priority
• Tracks message counts and timestamps

Agents Table

• Agent profiles and availability
• Indexed by email and status
• Tracks active conversation load

API Reference

WebSocket Routes

Connect

wscat -c "wss://your-api-id.execute-api.region.amazonaws.com/stage?user={\"email\":\"[email protected]\",\"name\":\"John Doe\"}&conversationId=conv123"

Query Parameters:

• user: JSON string with user information (must include email, optionally name)
• conversationId: (Optional) Conversation to join. If not provided or doesn't exist, a new conversation will be created

Auto-Creation Behavior:

• If the customer doesn't exist (by email), a new customer is created automatically
• If no conversationId is provided or the provided ID doesn't exist, a new conversation is created with:
  • Status: open
  • Priority: low
  • Channel: web
  • The customer who initiated the connection is tracked as the conversation owner

Send Message

{
  "action": "sendMessage",
  "data": {
    "conversationId": "conv123",
    "content": "Hello, I need help",
    "messageType": "text"
  }
}

Typing Indicator

{
  "action": "typing",
  "data": {
    "conversationId": "conv123",
    "isTyping": true
  }
}

REST API Endpoints

While this service primarily uses WebSocket for real-time communication, REST endpoints are available for:

Customers

• POST /customers - Create customer
• GET /customers/:customerId - Get customer
• PUT /customers/:customerId - Update customer
• GET /customers - List customers
• GET /customers/search?email= - Search by email

Conversations

• POST /conversations - Create conversation
• GET /conversations/:conversationId - Get conversation
• PUT /conversations/:conversationId - Update conversation
• GET /conversations?customerId= - List conversations
• PUT /conversations/:conversationId/assign - Assign to agent
• PUT /conversations/:conversationId/close - Close conversation

Agents

• POST /agents - Create agent
• GET /agents/:agentId - Get agent
• PUT /agents/:agentId - Update agent
• PUT /agents/:agentId/status - Update status
• GET /agents - List agents
• GET /agents/available - Get available agents

Messages

• GET /messages?conversationId= - List messages
• GET /messages/:messageId - Get message
• GET /messages/search?q= - Search messages
• GET /messages/:conversationId/stats - Get stats

File Attachments

• POST /attachments/upload-url - Generate presigned S3 upload URL

File Upload Flow:

The file upload system uses a secure presigned URL approach:

1. Request Upload URL

curl -X POST https://your-api.com/attachments/upload-url \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "document.pdf",
    "contentType": "application/pdf",
    "fileSize": 1234567
  }'

2. Response

{
  "data": {
    "uploadUrl": "https://s3.amazonaws.com/...",
    "attachmentUrl": "https://d123abc.cloudfront.net/attachments/uuid.pdf",
    "key": "attachments/uuid.pdf",
    "expiresIn": 300
  }
}

3. Upload File

curl -X PUT "presigned-upload-url" \
  -H "Content-Type: application/pdf" \
  --data-binary "@document.pdf"

4. Use CloudFront URL The attachmentUrl can be used in messages and will be served via CloudFront CDN.

Supported File Types:

• Images: JPEG, PNG, GIF, WebP
• Documents: PDF, DOC, DOCX
• Text: TXT, CSV
• Max file size: 10MB

Infrastructure:

• Files are stored in S3 with CORS enabled
• CloudFront distribution provides fast, global access
• Presigned URLs expire after 5 minutes for security

Deployment

Prerequisites

• AWS Account with appropriate permissions
• AWS CLI configured
• Node.js 18+ installed
• pnpm package manager

Environment Variables

Create a .env file in the root directory:

MONITORING_PROVIDER=sentry
SENTRY_DSN=your-sentry-dsn
ROLLBAR_ACCESS_TOKEN=your-rollbar-token
LOGTAIL_TOKEN=your-logtail-token
LOGTAIL_HTTP_API_URL=https://in.logtail.com

Deploy to Development

pnpm dev

This starts the SST development environment with hot reloading.

Deploy to Production

pnpm deploy --stage prod

Remove Stack

pnpm remove

Usage Examples

Customer-Agent Chat Flow

1. Customer Initiates Chat

   • Customer connects to WebSocket with email and name
   • System checks if customer exists (by email), creates if needed
   • System checks if conversation exists:
     • If conversationId provided and exists: joins existing conversation
     • If conversationId not provided or doesn't exist: creates new conversation with open status and low priority
   • System tracks the customer who initiated the conversation
   • System can optionally find available agent and assign conversation

2. Real-Time Communication

   • Customer sends messages
   • Agent receives messages in real-time
   • Agent responds
   • Customer sees typing indicators
   • Both parties receive messages instantly

3. Conversation Close

   • Agent or customer closes conversation
   • Customer rates satisfaction
   • Conversation is archived
   • Agent capacity is freed

Integration Example

// Connect to WebSocket
const user = { email: '[email protected]', name: 'John Doe' };
const ws = new WebSocket(
  'wss://your-api-id.execute-api.region.amazonaws.com/stage' +
  `?user=${encodeURIComponent(JSON.stringify(user))}`
  // conversationId is optional - will be auto-created if not provided
);

// Handle connection
ws.onopen = () => {
  console.log('Connected to chat');
};

// Handle incoming messages
ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  
  // Connection response includes conversationId and customerId
  if (response.conversationId) {
    console.log('Connected to conversation:', response.conversationId);
    console.log('Customer ID:', response.customerId);
  }
  
  if (response.type === 'message') {
    console.log('New message:', response.data);
  } else if (response.type === 'typing') {
    console.log('User is typing:', response.data);
  }
};

// Send a message (use conversationId from connection response)
ws.send(JSON.stringify({
  action: 'sendMessage',
  data: {
    conversationId: 'conv123', // from connection response
    content: 'Hello, I need help with my order',
    messageType: 'text'
  }
}));

// Send typing indicator
ws.send(JSON.stringify({
  action: 'typing',
  data: {
    conversationId: 'conv123', // from connection response
    isTyping: true
  }
}));

Data Models

Customer

{
  id: string;
  email: string;
  name: string;
  phone?: string;
  company?: string;
  customFields?: Record<string, unknown>;
  tags?: string[];
  status: 'active' | 'blocked';
  createdAt: string;
  updatedAt: string;
  lastSeenAt?: string;
  totalConversations?: number;
  notes?: string;
}

Conversation

{
  id: string;
  customerId: string;
  assignedAgentId?: string;
  status: 'open' | 'pending' | 'closed' | 'archived';
  priority: 'low' | 'medium' | 'high' | 'urgent';
  subject?: string;
  channel: 'web' | 'mobile' | 'email';
  tags?: string[];
  createdAt: string;
  updatedAt: string;
  closedAt?: string;
  lastMessageAt?: string;
  messageCount?: number;
  unreadCount?: number;
  satisfaction?: 1 | 2 | 3 | 4 | 5;
  metadata?: Record<string, unknown>;
  // Denormalized user information (no need to query separately)
  customer?: {
    id: string;
    email: string;
    name: string;
    phone?: string;
    company?: string;
    avatar?: string;
  };
  assignedAgent?: {
    id: string;
    email: string;
    name: string;
    avatar?: string;
  };
}

Message

{
  id: string;
  conversationId: string;
  senderId: string;
  senderType: 'customer' | 'agent' | 'system';
  content: string;
  messageType: 'text' | 'image' | 'file' | 'system';
  createdAt: string;
  status: 'sent' | 'delivered' | 'read';
  metadata?: Record<string, unknown>;
}

Agent

{
  id: string;
  email: string;
  name: string;
  avatar?: string;
  status: 'online' | 'offline' | 'away' | 'busy';
  capacity: number;
  activeConversations: number;
  skills?: string[];
  createdAt: string;
  updatedAt: string;
  lastActivityAt?: string;
}

Best Practices

Connection Management

• Implement reconnection logic with exponential backoff
• Handle connection errors gracefully
• Clean up connections on page unload

Message Handling

• Implement message queuing for offline scenarios
• Use optimistic UI updates
• Handle message delivery failures

Performance

• Use pagination for message history
• Implement message batching for high-volume scenarios
• Cache frequently accessed data
• Denormalized Data: Conversations include embedded customer and agent information to avoid extra queries
  • Customer info is embedded when conversation is created
  • Agent info is embedded when agent is assigned
  • Note: Updates to customer/agent profiles won't automatically update existing conversations (this is a performance trade-off)

Security

• Implement authentication/authorization
• Validate all input data
• Use WSS (secure WebSocket) in production
• Implement rate limiting

Monitoring

The service includes comprehensive monitoring via:

• AWS CloudWatch Logs
• AWS X-Ray Tracing
• Sentry error tracking
• Rollbar monitoring
• Logtail log aggregation

Knowledge Base Feature

The chat API now includes a comprehensive AI-powered knowledge base feature using AWS Bedrock, LangChain, and vector embeddings for RAG (Retrieval Augmented Generation) powered responses.

Features

• Document Upload: Support for PDF, TXT, DOC, and DOCX files
• Automatic Processing: Extract text and generate vector embeddings
• Semantic Search: Find relevant information using cosine similarity
• AI Responses: Claude 3 Sonnet generates answers with source citations
• Per-Conversation Toggle: Enable/disable knowledge base per conversation
• Management UI: Admin interface for uploading and managing documents

Quick Start

1. Navigate to /dashboard/knowledge-base in the admin UI
2. Upload documents (PDF, TXT, DOC, DOCX)
3. Enable knowledge base for a conversation using the toggle
4. Ask questions - the chatbot will use your documents to provide accurate answers

For detailed documentation, see KNOWLEDGE_BASE.md

Agent Status Management

The system includes intelligent agent availability tracking and automatic routing:

• Agents are tracked for activity with automatic idle detection
• After 5 minutes of inactivity, agents are automatically marked as "away"
• Customer messages are routed to human agents when available
• AI chatbot only responds when no human agents are online and active
• Scheduled cleanup runs every 2 minutes to maintain agent status accuracy

For detailed documentation, see AGENT_STATUS_MANAGEMENT.md

Future Enhancements

• [x] File and image upload support
• [x] Knowledge base integration
• [ ] Agent-to-agent messaging
• [ ] Advanced conversation routing rules
• [ ] Real-time analytics dashboard
• [ ] Multi-language support
• [ ] Video/audio call integration
• [ ] Conversation transcripts via email
• [ ] Canned responses
• [ ] Department-based routing
• [ ] Business hours management
• [ ] Queue management for high traffic
• [ ] SLA tracking and alerts

License

MIT

Support

For issues and questions, please contact the development team or create an issue in the repository.