📣 Stentor Chat Router

A WebSocket-based message routing system that acts as a "post office" and "switchboard" for chat communications. It connects chat widgets to Stentor bot services, handling message relay, session management, and multi-channel notifications.

Installation

npm install @xapp/stentor-chat-router
# or
yarn add @xapp/stentor-chat-router

Architecture Overview

Core Components

1. Message Router (PostOffice)

The PostOffice class (src/delivery/PostOffice.ts) is the central hub for all message routing. It:

• Manages connected endpoints (widgets, bots, admins)
• Routes messages between participants in a session
• Handles broadcasting to multiple recipients
• Tracks message history for conversation continuity
• Manages alerts and notifications through multiple channels (Email, SMS, Slack)

2. WebSocket Handler

The main Lambda entry point (src/index.ts:wsHandler) processes WebSocket events:

• CONNECT: Establishes new connections and creates endpoints
• MESSAGE: Routes messages between participants
• DISCONNECT: Cleans up connections and notifies participants

3. Connectors

Different connector types handle platform-specific integrations:

• WidgetConnector: Manages web widget connections via WebSocket
• StentorConnector: Connects to Stentor bot services with retry logic and typing indicators
• GenesisConnector: Integrates with Genesys Cloud platform

Data Flow

1. Connection Establishment

   • Client connects via WebSocket → Creates an Endpoint → Stored in DynamoDB
   • Each endpoint has a unique userId and connectionId

2. Message Routing

   • Messages arrive with RouterMessage format containing event type, data, sender info, and session ID
   • PostOffice determines recipients based on session participants
   • Messages are broadcasted to all relevant endpoints

3. Session Management

   • Sessions group participants together for conversations
   • Message history is maintained per session
   • Sessions persist across connections for conversation continuity

Data Models

• Endpoint: Represents a connected client with connection details, permissions (sends/receives), and visitor information
• Session: Contains conversation participants, message history, and metadata
• RouterMessage: Standard format for all messages with event types like "new message", "typing", "user joined", etc.

Storage

• DynamoDB Tables:
  • Endpoints table: Stores active connections
  • Sessions table: Maintains conversation history and participant lists
• AWS Secrets Manager: Stores API credentials and sensitive configuration

Deployment

The project uses Serverless Framework with three Lambda functions:

• ws: WebSocket handler for real-time connections
• app: HTTP POST handler for webhook integrations (e.g., Google Business Messages)
• html: Static file server for widget HTML/JS/CSS

Quick Start

Basic WebSocket Handler

Create a Lambda function entry point using the provided handlers:

import {
  wsConnectionHandler,
  wsDisconnectionHandler,
  wsMessageHandler,
  PostOffice,
} from "@xapp/stentor-chat-router";

export async function wsHandler(
  event: any,
  context?: any,
  callback?: any
): Promise<any> {
  // Initialize PostOffice with your configuration
  const postOffice = new PostOffice({ 
    topic: "your-topic",
    // Add your configuration options
  });

  const eventType = event.requestContext.eventType;

  switch (eventType) {
    case "MESSAGE":
      return wsMessageHandler(event, context, callback, postOffice);

    case "CONNECT":
      return wsConnectionHandler(event, context, callback, postOffice);

    case "DISCONNECT":
      return wsDisconnectionHandler(event, context, callback, postOffice);

    default:
      return callback(new Error(`Invalid eventType "${eventType}"`));
  }
}

PostOffice Configuration

The PostOffice class is the central message router. Initialize it with your specific configuration:

import { PostOffice } from "@xapp/stentor-chat-router";

const postOffice = new PostOffice({
  topic: "your-chat-topic",
  // Additional configuration options based on your needs
});

API Reference

Main Exports

• wsConnectionHandler - Handles WebSocket connection events
• wsDisconnectionHandler - Handles WebSocket disconnection events
• wsMessageHandler - Handles WebSocket message events
• PostOffice - Central message routing class

Core Classes

• PostOffice - Message router and session manager
• Endpoint - Represents connected clients
• Session - Manages conversation state
• RouterMessage - Standard message format

Deployment

For AWS deployment, the package includes Serverless Framework configuration. You can deploy it as a standalone service or integrate the handlers into your existing Lambda functions.

Environment Variables

Set the following environment variables for proper operation:

• CONNECTION_SERVER_URL - WebSocket connection URL for widgets
• STUDIO_APP_ID - (Optional) For single-app deployments

Prerequisites

• Node.js 18+ or 20+
• AWS account (for deployment)
• DynamoDB tables for sessions and endpoints