A comprehensive real-time chat API with WebSocket support and full CRM capabilities for customer support and relationship management.
npm install @xcelsior/chat-apiA comprehensive real-time chat API with WebSocket support and full CRM capabilities for customer support and relationship management.
#### 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
#### 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:open
- Status: low
- Priority: web
- Channel:
- 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
}
}
While this service primarily uses WebSocket for real-time communication, REST endpoints are available for:
#### Customers
- POST /customers - Create customerGET /customers/:customerId
- - Get customerPUT /customers/:customerId
- - Update customerGET /customers
- - List customersGET /customers/search?email=
- - Search by email
#### Conversations
- POST /conversations - Create conversationGET /conversations/:conversationId
- - Get conversationPUT /conversations/:conversationId
- - Update conversationGET /conversations?customerId=
- - List conversationsPUT /conversations/:conversationId/assign
- - Assign to agentPUT /conversations/:conversationId/close
- - Close conversation
#### Agents
- POST /agents - Create agentGET /agents/:agentId
- - Get agentPUT /agents/:agentId
- - Update agentPUT /agents/:agentId/status
- - Update statusGET /agents
- - List agentsGET /agents/available
- - Get available agents
#### Messages
- GET /messages?conversationId= - List messagesGET /messages/:messageId
- - Get messageGET /messages/search?q=
- - Search messagesGET /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
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
`bash`
pnpm dev
This starts the SST development environment with hot reloading.
`bash`
pnpm deploy --stage prod
`bash`
pnpm remove
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
`typescript?user=${encodeURIComponent(JSON.stringify(user))}
// 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' +
// 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
}
}));
`
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 limitingMonitoring
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 UIFor detailed documentation, see KNOWLEDGE_BASE.md
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
- [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
MIT
For issues and questions, please contact the development team or create an issue in the repository.