Chat core library with MongoDB and Redis support
npm install wexa-chatTypeScript chat core for MongoDB with optional Redis and a built‑in WebSocket transport. Ships server APIs and a lightweight browser client bundle used by the demo app.
- Server: import { initChat } from 'wexa-chat'
- Client: import { SocketProvider, useSocket, getSocketManager, type ChatEvent } from 'wexa-chat/client'
This README mirrors the integration used in the Next.js demo app.
``bash`
npm install wexa-chat mongoose ioredis
Initialize once with initChat(mongoose, options, httpServer?). If your app starts before an HTTP server exists (e.g., SSR), you can re‑initialize later with the server to attach the WebSocket transport.
`ts
import mongoose from 'mongoose';
import type { Server as HTTPServer } from 'http';
import { initChat } from 'wexa-chat';
let chatInstance: Awaited
export async function getChatInstance(httpServer?: HTTPServer) {
if (chatInstance) {
// Attach WS transport when server becomes available
if (httpServer && !(chatInstance.transport as any).socket) {
chatInstance = await initChat(mongoose, {
participantModels: ['User'],
memberRoles: ['member', 'admin'],
mongoUri: process.env.MONGODB_URI!,
// Optional Redis for cross‑instance fanout
redis: process.env.REDIS_URL || process.env.REDIS_HOST
? { url: process.env.REDIS_URL, host: process.env.REDIS_HOST, port: Number(process.env.REDIS_PORT || 6379) }
: undefined,
// IMPORTANT: must match the client (recommended '/ws')
socket: { path: '/ws' },
enableTextSearch: true,
}, httpServer);
}
return chatInstance;
}
// First‑time init; only pass socket when server exists
chatInstance = await initChat(mongoose, {
participantModels: ['User'],
memberRoles: ['member', 'admin'],
mongoUri: process.env.MONGODB_URI!,
redis: process.env.REDIS_URL || process.env.REDIS_HOST
? { url: process.env.REDIS_URL, host: process.env.REDIS_HOST, port: Number(process.env.REDIS_PORT || 6379) }
: undefined,
socket: httpServer ? { path: '/ws' } : undefined,
enableTextSearch: true,
}, httpServer);
return chatInstance;
}
`
- Transport uses native ws and attaches an HTTP upgrade listener when httpServer is provided.socket.path
- Set to the URL path for upgrades. The client bundle expects /ws; configure the same on the server.ws(s)://host/ws?userId=...&userModel=User
- Authentication: client connects to . The server validates the handshake and associates the user.
Warm the server so the upgrade listener is attached before the browser connects:
`ts
// pages/api/socket.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import type { Server as HTTPServer } from 'http';
import { getChatInstance } from '@/lib/chat';
export const config = { api: { bodyParser: false } };
export default async function handler(_req: NextApiRequest, res: NextApiResponse) {
const server = (res.socket as any).server as HTTPServer;
await getChatInstance(server);
res.status(200).end('OK');
}
`
The browser client performs a one‑time GET of /api/socket before opening the WebSocket.
)`ts
export type SocketConfig = {
path?: string;
cors?: { origin?: string | string[]; methods?: string[] };
};
export type InitOptions = {
participantModels: string[]; // e.g. ['User']
memberRoles: string[]; // e.g. ['member', 'admin']
mongoUri: string; // MongoDB connection
enableTextSearch?: boolean;
redis?: { // optional
url?: string; host?: string; port?: number; password?: string; db?: number;
socketConnectTimeout?: number; keepAlive?: number;
};
socket?: SocketConfig; // WebSocket config
presence?: { enabled?: boolean; heartbeatSec?: number };
rateLimit?: { sendPerMin?: number; typingPerMin?: number };
}
`
chat.services exposes conversations and messages services.
- Conversations
- createOrFindConversation({ organizationId, a:{model,id}, b:{model,id} })
-
-
-
- Messages
- sendMessage({ organizationId, conversationId, senderModel, senderId, text, source, kind?, parentMessageId?, rootThreadId?, connectorIds? })
-
-
-
-
-
-
DTO types live in src/types/dto.ts.
The listMessagesWithSenders method allows you to retrieve messages with populated sender details, optimized for infinite scroll in chat interfaces. The implementation uses efficient batched lookups:
`ts
// Basic usage
const messagesWithSenders = await chat.services.messages.listMessagesWithSenders({
organizationId: 'org-123',
conversationId: 'conv-456',
populateSenders: true // Required to enable population
});
// With customization
const messagesWithCustomSenders = await chat.services.messages.listMessagesWithSenders({
organizationId: 'org-123',
conversationId: 'conv-456',
populateSenders: true,
populateOptions: {
fields: '_id name email profilePicture', // Fields to select from sender model
modelMapping: {
'User': 'CustomUserModel', // If your senderModel doesn't match the actual Mongoose model name
'Bot': 'BotModel'
}
}
});
// Accessing populated data
messagesWithSenders.items.forEach(message => {
console.log(Message from ${message.sender?.name}: ${message.text});`
});
The populated sender data is available in the sender property of each message. The implementation uses a batched approach that:
1. Fetches messages using MongoDB aggregation
2. Groups messages by sender model type
3. Loads all senders for each model type in a single query per model
4. Attaches sender data to each message efficiently
This approach minimizes database queries and maximizes performance, even with multiple sender types.
#### Infinite Scroll Implementation
The returned data structure supports infinite scroll with cursor-based pagination:
`ts
// First load
const firstPage = await chat.services.messages.listMessagesWithSenders({
organizationId: 'org-123',
conversationId: 'conv-456',
populateSenders: true,
limit: 20 // Number of messages per "page"
});
// Display messages in your UI
displayMessages(firstPage.items);
// When user scrolls and needs more messages
if (firstPage.hasMore) {
// Load next batch using the cursor
const nextPage = await chat.services.messages.listMessagesWithSenders({
organizationId: 'org-123',
conversationId: 'conv-456',
populateSenders: true,
limit: 20,
cursor: firstPage.nextCursor // Pass the cursor from previous batch
});
// Append these messages to your UI
displayMessages([...existingMessages, ...nextPage.items]);
// Store the new cursor for further loading
nextCursor = nextPage.nextCursor;
hasMore = nextPage.hasMore;
}
`
The method returns messages sorted by creation time (newest first), making it ideal for chat interfaces where newer messages appear at the bottom. The cursor-based pagination ensures efficient loading of large conversation histories.
The type MessageWithSender is exported from the package for proper TypeScript support.
Messages include a required source field (array) to indicate one or more origins for a message. Valid values are enforced by an enum of strings:
`ts
export const sourceType = {
LINKEDIN: 'linkedin',
WHATSAPP: 'whatsapp',
EMAIL: 'email',
CORE: 'core',
} as const;
export type SourceType = (typeof sourceType)[keyof typeof sourceType];
`
When sending a message via sendMessage, you must provide source: SourceType[]. For internal server‑generated messages, use [sourceType.CORE].
If you include external connectors in the source (e.g., linkedin, whatsapp, email), you can optionally pass connectorIds to perform the external send and to persist identifiers for quick follow‑ups.
#### Email with Rich Metadata
Email supports advanced features like subject lines, CC/BCC, attachments, and tracking:
`ts
// Simple email
await chat.services.messages.sendMessage({
organizationId: 'org-123',
conversationId: 'conv-456',
senderModel: 'User',
senderId: 'user-1',
text: 'Hi John,\n\nInterested in discussing a role?\n\nBest,\nJane',
source: [sourceType.EMAIL],
connectorIds: {
email: { connectorId: 'em-connector-1', contactId: 'john@candidate.com' },
},
metadata: {
email: {
subject: 'Job Opportunity at TechCorp',
recipientName: 'John Doe',
}
}
});
// Full-featured email with all options
await chat.services.messages.sendMessage({
organizationId: 'org-123',
conversationId: 'conv-456',
senderModel: 'User',
senderId: 'user-1',
text: 'Dear John,\n\nWe are looking for a Senior Software Engineer...',
source: [sourceType.EMAIL],
connectorIds: {
email: { connectorId: 'em-connector-1', contactId: 'john@candidate.com' },
},
metadata: {
email: {
subject: 'Senior Software Engineer Position - TechCorp',
recipientName: 'John Doe',
cc: [
{ display_name: 'HR Manager', identifier: 'hr@techcorp.com' }
],
bcc: [
{ display_name: 'Recruiting Lead', identifier: 'lead@techcorp.com' }
],
attachments: [
'https://storage.company.com/job-description.pdf',
'https://storage.company.com/company-overview.pdf'
],
tracking: {
opens: true,
links: true,
label: 'q1_2024_recruitment'
}
}
}
});
// Email reply (threading)
await chat.services.messages.sendMessage({
organizationId: 'org-123',
conversationId: 'conv-456',
senderModel: 'User',
senderId: 'user-1',
text: 'Hi John,\n\nThank you for your response!...',
source: [sourceType.EMAIL],
connectorIds: {
email: { connectorId: 'em-connector-1', contactId: 'john@candidate.com' },
},
metadata: {
email: {
subject: 'Re: Senior Software Engineer Position',
recipientName: 'John Doe',
replyTo: 'email_provider_id_abc123xyz' // From previous email
}
},
parentMessageId: 'msg-previous-id',
rootThreadId: 'msg-root-id'
});
`
#### Multi-Platform Messages
`ts`
await chat.services.messages.sendMessage({
organizationId: 'org-123',
conversationId: 'conv-456',
senderModel: 'User',
senderId: 'user-1',
text: 'Hello from Wexa',
source: [sourceType.CORE, sourceType.LINKEDIN, sourceType.WHATSAPP],
connectorIds: {
linkedin: { connectorId: 'ln-connector-1', contactId: 'https://linkedin.com/in/someone' },
whatsapp: { connectorId: 'wa-connector-1', contactId: '+1 234 567 8901' },
},
});
Under the hood (src/services/messages.service.ts):
- LinkedIn: posts to the LinkedIn connector with { linkedin_url, text }.{ phone_numbers, text }
- WhatsApp: posts to the WhatsApp connector with (phone is sanitized to remove spaces and a leading +)./mail/send_email/:connectorId
- Email: posts to with complete payload including to (array of recipients with display_name and identifier), body, subject, cc, bcc, attachments (URLs), reply_to (for threading), and tracking_options.source
- Each external task runs concurrently. A successful task's remains in the stored message. Failures are collected into a failed_source array attached to the returned message instance at runtime: message.failed_source: Array<{ source: string; message: string }>.lastLinkedInId: string
- The conversation document is updated with last message metadata and, when applicable, with connector identifiers:
- — set from connectorIds.linkedin.contactId when source includes linkedin.lastWhatsAppId: string
- — set from a sanitized connectorIds.whatsapp.contactId when source includes whatsapp.lastEmailId: string
- — set from connectorIds.email.contactId when source includes email.metadata.email
- Message metadata (subjects, CC/BCC, attachments, tracking info) is stored in the field for reference and UI rendering.
This allows subsequent UI actions to prefill the last known contact handles for LinkedIn, WhatsApp, and Email.
When an external connector delivers a new inbound message, you can persist it directly using the chat ID stored on the conversation.
Important: Deduplication - All receive methods support automatic deduplication via messageId. If a message with the same messageId already exists in the conversation, the existing message is returned instead of creating a duplicate. This prevents duplicate messages from webhooks that retry or are delivered multiple times.
#### WhatsApp Messages
`ts`
await chat.services.messages.receiveWhatsappMessage({
whatsappChatId: 'wa-chat-123',
message: 'Hello from WhatsApp',
messageId: 'wamid.HBgNMTIzNDU2Nzg5...', // For deduplication
senderName: 'John Doe', // Optional
});
#### LinkedIn Messages
`ts`
await chat.services.messages.receiveLinkedinMessage({
linkedinChatId: 'li-chat-456',
message: 'Hello from LinkedIn',
messageId: 'msg-abc123', // For deduplication
senderName: 'Jane Smith', // Optional
senderProfileUrl: 'https://linkedin.com/in/janesmith', // Optional
});
#### Email with Full Metadata
Email receives support enhanced metadata including subject, sender info, and threading:
`ts
// Simple email reply
await chat.services.messages.receiveEmailMessage({
emailChatId: 'em-chat-789',
message: 'Hi! I\'m interested in the role.',
subject: 'Re: Job Opportunity',
senderEmail: 'candidate@example.com',
senderName: 'John Doe',
messageId: '
});
// Full email with threading and attachments
await chat.services.messages.receiveEmailMessage({
emailChatId: 'em-chat-789',
message: 'Hi Jane,\n\nThank you for reaching out...',
subject: 'Re: Senior Developer Position',
senderEmail: 'candidate@example.com',
senderName: 'John Doe',
providerId: '19bfed8cdc1d7148', // For threading - important!
messageId: '
attachments: [
{
name: 'resume.pdf',
url: 'https://storage.example.com/resume.pdf',
size: 245000,
mimeType: 'application/pdf'
}
]
});
`
All helpers will:
1. Check for duplicates - If messageId is provided, check if a message with that ID already exists in the conversation and return it if found.Application
2. Locate the conversation by the given chat ID.
3. Use the participant from the conversation as the sender.kind: 'text'
4. Create a new message with and source set to the respective connector.metadata.email
5. Store platform-specific metadata:
- Email: subject, sender info, attachments, threading data in
- LinkedIn: sender name and profile URL in
- WhatsApp: sender name in
6. Update the conversation summary fields (, lastMessagePreview, lastMessageSenderId, lastMessageSenderModel).
The package exports the following model types which can be imported directly:
`ts`
import {
// Model interfaces (document structures)
type IConversation,
type IMessage,
// Mongoose model types
type ConversationModel,
type MessageModel,
// Extended types
type MessageWithSender // Message with populated sender data
} from 'wexa-chat';
To access the actual models:
`ts
// Initialize the chat system
const chat = await initChat(mongoose, options);
// Access models
const { Conversation, Message } = chat.models;
// Example usage
const conversations = await Conversation.find({ organizationId }).lean();
const messages = await Message.find({ conversationId }).sort({ createdAt: -1 }).lean();
`
Entry: wexa-chat/client exports SocketProvider, useSocket, getSocketManager, and type ChatEvent.
Wrap your app:
`tsx
import { SocketProvider } from 'wexa-chat/client';
export default function App({ children }: { children: React.ReactNode }) {
const getUserId = () => mySession?.user?.id as string | undefined;
return
}
`
Use in components:
`tsx
import { useEffect } from 'react';
import { useSocket, type ChatEvent } from 'wexa-chat/client';
export function ChatWindow({ conversationId }: { conversationId: string }) {
const { isConnected, send, onEvent } = useSocket();
useEffect(() => {
if (!conversationId) return;
if (isConnected) send({ type: 'join-conversation', conversationId });
const off = onEvent((e: ChatEvent) => {
if (e.type === 'message:created' && e.message?.conversationId === conversationId) {
// update UI
}
});
return off;
}, [conversationId, isConnected, send, onEvent]);
return null;
}
`
You can also send:
`ts`
send({ type: 'leave-conversation', conversationId });
send({ type: 'typing', conversationId, isTyping: true });
- message:created — { type: 'message:created', message }
- — { type: 'conversation:read', conversationId, messageId, participantModel, participantId, at }
- — { type: 'typing', conversationId, participantModel, participantId, state: 'start' | 'stop' }
- / presence:leave — { type, organizationId, participantModel, participantId, at }
If Redis is configured, events are pub/sub‑broadcast across instances.
`bash`
npm run build
Exports (from package.json):
`json`
{
"exports": {
".": { "import": "./dist/index.mjs", "require": "./dist/index.js", "types": "./dist/index.d.ts" },
"./client": { "import": "./dist/client/index.js", "types": "./dist/client/index.d.ts" }
}
}
- MONGODB_URI
- or REDIS_HOST/REDIS_PORT/REDIS_PASSWORD/REDIS_DB
- Ensure matches the client (recommended /ws`).
MIT