Live Chat API

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

Features

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

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

Architecture

$3

- 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

$3

#### 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

$3

#### Connect
``
wscat -c "wss://your-api-id.execute-api.region.amazonaws.com/stage?user={\"email\":\"user@example.com\",\"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
`json
{
"action": "sendMessage",
"data": {
"conversationId": "conv123",
"content": "Hello, I need help",
"messageType": "text"
}
}
`

#### Typing Indicator
`json
{
"action": "typing",
"data": {
"conversationId": "conv123",
"isTyping": true
}
}
`

$3

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
`bash
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
`json
{
"data": {
"uploadUrl": "https://s3.amazonaws.com/...",
"attachmentUrl": "https://d123abc.cloudfront.net/attachments/uuid.pdf",
"key": "attachments/uuid.pdf",
"expiresIn": 300
}
}
`

3. Upload File
`bash
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

$3

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

$3

Create a .env file in the root directory:

`env
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
`

$3

`bash
pnpm dev
`

This starts the SST development environment with hot reloading.

$3

`bash
pnpm deploy --stage prod
`

$3

`bash
pnpm remove
`

Usage Examples

$3

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

$3

`typescript
// Connect to WebSocket
const user = { email: 'customer@example.com', 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

$3


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

$3

`typescript
{
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;
// 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;
};
}
`

$3

`typescript
{
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;
}
`

$3

`typescript
{
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

$3

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

$3

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

$3

- 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)

$3

- 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.

$3

- 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

$3

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.