WebChat

SetupCopy Anchor Link

pnpm add ws

UsageCopy Anchor Link

import { webchatChannel } from '@cogitator-ai/channels';

const webchat = webchatChannel({
  port: 3100,
  path: '/ws',
  auth: (token) => token === process.env.WEBCHAT_TOKEN,
});

Use with cogitator upCopy Anchor Link

Add a webchat entry to cogitator.yml and set WEBCHAT_TOKEN in the .env next to it:

channels:
  webchat:
    port: 8080 # default
    path: /ws # default

WEBCHAT_TOKEN=a-long-random-secret

Clients connect to ws://localhost:8080/ws?token=<WEBCHAT_TOKEN>. Without WEBCHAT_TOKEN the channel is not started (a warning is logged), because an open socket would give anyone the assistant's tools. WebChat has no ownerIds: every connection is a separate anonymous user. cogitator wizard --edit keeps the entry. See the config reference.

ConfigurationCopy Anchor Link

interface WebChatConfig {
  port: number;
  path?: string; // default: '/ws'
  auth?: (token: string) => boolean;
  maxPayload?: number; // max incoming frame size in bytes, default 1 MiB
}

ConnectingCopy Anchor Link

WebSocket URL: ws://localhost:3100/ws?token=YOUR_SECRET

With wscatCopy Anchor Link

npx wscat -c "ws://localhost:3100/ws?token=secret"
> {"text": "Hello!"}

From JavaScriptCopy Anchor Link

const ws = new WebSocket('ws://localhost:3100/ws?token=secret');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'message') console.log('Bot:', msg.text);
  if (msg.type === 'edit') console.log('Bot (updated):', msg.text);
};
ws.onopen = () => ws.send(JSON.stringify({ text: 'Hi!' }));

ProtocolCopy Anchor Link

Client → ServerCopy Anchor Link

{ "text": "Hello!", "id": "optional-id" }

Server → ClientCopy Anchor Link

Frames that are not JSON or have no non-empty text string are ignored.

FeaturesCopy Anchor Link

TipsCopy Anchor Link

• Perfect for building custom chat UIs
• Auth is optional but recommended for production
• Each WebSocket connection is treated as a separate user: channelId and userId are the random clientId, so a reconnect starts a new thread
• Incoming messages carry text only — attachments are not supported from the client
• start() rejects if the port is already in use; stop() closes all client connections (code 1001)
• Use with reverse proxy (nginx) for TLS in production