Get Started with EdgeInteract

EdgeInteract requires EdgeStream as its communication foundation. This guide walks you from installation through setting context, publishing messages, and controlling your first UI component.

Installation

1
Install EdgeStream and core EdgeInteract packages

EdgeStream is the required communication foundation. Install it first, then add the EdgeInteract packages you need.

pnpm add edge-stream-js pnpm add @edge-interact/context-data-js pnpm add @edge-interact/context-manager pnpm add @edge-interact/comm-manager pnpm add @edge-interact/player-manager pnpm add @edge-interact/client pnpm add @edge-interact/built-in-plugins
2
Add React integration (optional)

If you are using React, add the hooks and UI packages. The vanilla JS chat window works without React.

pnpm add @edge-interact/react-hooks pnpm add @edge-interact/react-ui pnpm add @edge-interact/integration

Create the client

3
Initialise EdgeStream and create the EdgeInteract client

The EdgeInteractClientService is the single facade for the entire system. Pass it an EdgeStream instance and it wires up ContextManager, CommManager, and PlayerManager automatically.

import { EdgeStream } from 'edge-stream-js'; import { EdgeInteractClientService } from '@edge-interact/client'; // 1. Create EdgeStream const edgeStream = new EdgeStream({ serverUrl: 'wss://your-server.com/ws', reconnect: true }); // 2. Create EdgeInteract client const client = EdgeInteractClientService.create(edgeStream, { logLevel: 'info', enableObservability: true }); // Full API available at: // client.state — context management // client.players — UI control (chat, form, workflow) // client.comm — publish / subscribe // client.ui — plugin registration // client.errors — error handling // client.observability — health and logging
4
Set user and session context

Set context once after login. Every subsequent message published via client.comm automatically carries this context — you never pass it manually again.

import type { IUserData, ISessionData } from '@edge-interact/context-data-js'; // Set user context after authentication const user: IUserData = { role: 'user', userId: 'user-sarah-123', userName: 'Sarah Johnson', email: '[email protected]', permissions: ['read-orders', 'write-orders', 'view-customers'] }; client.state.setUser(user); // Set session context const session: ISessionData = { role: 'session', sessionId: 'sess-' + Date.now(), startTime: new Date().toISOString(), timezone: Intl.DateTimeFormat().resolvedOptions().timeZone, locale: navigator.language }; client.state.setSession(session);
From this point, every message published through EdgeInteract carries user.userId, user.permissions, session.sessionId, session.timezone, and session.locale — automatically. Your validation and routing hooks can access all of this without any additional lookup.

Open a conversation and send a message

5
Set conversation context

Before sending chat messages, set the active conversation. EdgeInteract uses this to isolate messages between users — User A's messages never reach User B's subscriber.

import type { IConversationData } from '@edge-interact/context-data-js'; const conversation: IConversationData = { role: 'conversation', conversationId: 'conv-support-456', type: 'chat', participants: ['user-sarah-123', 'bot-support'], createdAt: new Date().toISOString() }; client.state.setConversation(conversation);
6
Register the ChatWindowPlugin and display the chat

Register the built-in chat plugin, then use PlayerManager to display it. Every message sent or received carries the full context envelope.

import { ChatWindowPlugin } from '@edge-interact/built-in-plugins'; // Register the plugin const chatPlugin = new ChatWindowPlugin(); client.ui.register(chatPlugin, { containerId: 'chat-container', theme: 'dark' }); // Display the chat window await client.players.chat('conv-support-456').show(); // Send a message — context is added automatically await client.players.chat('conv-support-456').sendMessage({ text: 'Hello, I need help with my order', type: 'user' });
7
Subscribe to incoming messages

Subscribe to a topic with an optional context filter. The filter ensures you only receive messages for the current conversation — context isolation built in.

// Subscribe with context filter const subscription = client.comm.subscribe( 'messages:conversation:conv-support-456', (message) => { console.log('Received:', message.body); console.log('From user:', message.context.user.userName); console.log('Customer tier:', message.context.variables?.customerTier); // Display in chat window client.players.chat('conv-support-456').displayMessage(message); }, // Optional context filter — only messages for this conversation (context) => context.conversation?.conversationId === 'conv-support-456' ); // Later: unsubscribe subscription.unsubscribe();

Add a context enhancer

8
Register a custom context enhancer

Context enhancers run as a middleware pipeline on every message. Use them to add business data (customer tier, permissions, language) without changing any other code.

import type { IContextEnhancer, IContextualMessage } from '@edge-interact/context-manager'; class CustomerTierEnhancer implements IContextEnhancer { name = 'customer-tier'; priority = 10; // Lower = runs first async enhance(context: IContextualMessage): Promise { if (!context.context.entity?.id) return context; // Fetch from your API const tier = await fetchCustomerTier(context.context.entity.id); return { ...context, context: { ...context.context, variables: { ...context.context.variables, customerTier: tier // 'gold', 'silver', 'standard' } } }; } } // Register — runs on every outgoing message client.state.addEnhancer(new CustomerTierEnhancer());
After this enhancer is registered, every message in the pipeline will have context.variables.customerTier available — in validation hooks, routing hooks, bot handlers, and UI components. No boilerplate in each subscriber.
9
Use React hooks (if using React)

Wrap your app in EdgeInteractProvider once. Then use hooks anywhere in the component tree to access state, players, and subscriptions.

// App.tsx import { EdgeInteractProvider } from '@edge-interact/react-hooks'; export function App() { return ( <EdgeInteractProvider edgeStream={edgeStream} options={{}}> <SupportDashboard /> </EdgeInteractProvider> ); } // SupportDashboard.tsx import { useEdgeInteract, useChat } from '@edge-interact/react-hooks'; function SupportDashboard() { const { state, players } = useEdgeInteract(); const { messages, sendMessage } = useChat('conv-support-456'); const handleSend = async (text: string) => { await sendMessage({ text, type: 'user' }); }; return ( <div> {messages.map(msg => ( <div key={msg.messageId}> <strong>{msg.context.user.userName}</strong>: {msg.body.text} </div> ))} </div> ); }

Need help getting set up?

Ask in the EdgeInteract community or book a session with the BizFirstAi team.

Join the Community Book a Session