Chat | Weei

Widget ID: chat. API: documented below.

Purpose

A chat for everyone in the session, built into the page. Participants write to the whole session or privately to one participant, and can attach files and record short voice or video messages without leaving your application.

What it does

Feature	Details
Conversations	A general conversation with everyone, and a private conversation with each connected participant. Pick the conversation from the list at the top of the chat.
Messages	Text messages, sent directly between participants' browsers.
Files	Any file can be attached. Files are sent in parts, and the progress is shown while they are delivered.
Voice messages	Recorded from the microphone in the chat and played back inline.
Video messages	Recorded from the camera in the chat and played back inline.
Unread messages	Counted separately for the general and private conversations. The chat button in the control panel tray shows the total.
Window	The chat can be expanded to a larger size and minimized with its button or `Esc`.

Opening the chat

Chat is a mandatory widget: when it is enabled for your site, it is available to every participant and your page cannot turn it off. Participants open and minimize it with the chat button in the control panel tray. From your own interface, open the chat with open().

Delivery and history

Messages and files go directly from browser to browser through the session; they are not uploaded to Weei servers.
Only participants connected at the moment a message is sent receive it. A participant who joins later does not see earlier messages.
History is kept in memory and is lost when the page is reloaded or closed.
A private message is delivered only to its recipient.

Getting the API

The API is available as soon as loadWeei() resolves, if the widget is enabled for your site. The widget window does not need to be open.

JavaScript

const weei = await window.weeiReady;
const chat = weei.widgetsApi.get('chat');
if (!chat) throw new Error('Chat is not enabled for this site.');

TypeScript

interface ChatApi {
  getMessages(): ChatMessage[];
  subscribe(listener: (messages: ChatMessage[]) => void): () => void;
  send(text: string, options?: { to?: string; files?: File[] }): Promise<ChatMessage>;
  open(): void;    // opens the chat window
  close(): void;   // minimizes it
}

interface ChatMessage {
  id: string;
  from: string;          // peer ID of the sender
  to: string | null;     // recipient of a private message; null: the general chat
  text: string;          // '' for a message with files only
  files: File[];         // complete files only; a message appears once all its files arrive
  mine: boolean;         // sent by this browser
  time: number;          // when this browser sent or received it, ms since epoch
}

send() returns a promise and rejects with an Error for invalid input, a disconnected recipient or a sending failure. getMessages(), open() and close() are synchronous. subscribe() calls the listener at once with the current list, then on every change, and returns a function that unsubscribes. Lists are copies: changing them has no effect.

Method	Behavior
`getMessages()`	Messages of this session, oldest first: the general chat and this browser's private conversations. Messages from before the page loaded are not available.
`send(text, options?)`	Sends to everyone connected, or privately to `options.to`. Text is up to 10,000 characters; attach up to 10 `File` objects with `options.files`. Resolves once the message is sent — for files, once they have been read and sending has started — not when participants have received it. Rejects if the text and files are both empty or the recipient is not connected.
`open()`, `close()`	Open or minimize the chat window, as the tray button does.

Peer IDs are the ones the participants connector reports; use it to show names and to choose a recipient.

Example: post order updates and log replies

JavaScript

const weei = await window.weeiReady;
const chat = weei.widgetsApi.get('chat');

// A system message to everyone in the session
await chat.send('Order #1042 is paid. Shipping label is ready.');

// Keep a copy of the conversation in your own backend
const sent = new Set();
chat.subscribe(messages => {
  for (const message of messages) {
    if (sent.has(message.id)) continue;
    sent.add(message.id);
    fetch('/api/support-log', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ from: message.from, to: message.to, text: message.text, time: message.time })
    });
  }
});