Chat

@urth/metatell-sdk/chat lets a plugin send and receive in-room chat messages, including replies and mentions.

Receiving messages

import { onMessage } from "@urth/metatell-sdk/chat";

const unsubscribe = onMessage((message) => {
  console.log(`${message.from.displayName}: ${message.text}`);
});

// on teardown
unsubscribe();
Copy

A ChatMessage has the following shape:

interface ChatMessage {
  id: string;
  channel: "global" | "group";
  groupId?: string;
  from: { sessionId: string; displayName: string };
  text: string;
  mentions: Mention[];
  replyTo?: string;
  sentAt: number;
}
Copy

Sending messages

send() resolves with the resulting ChatMessage once the host confirms it.

import { send } from "@urth/metatell-sdk/chat";

const message = await send("hello world");
Copy

Options:

interface SendOptions {
  channel?: "global" | "group"; // default "global"
  groupId?: string;             // required for group channel
  replyTo?: string;             // id of the message being replied to
  timeoutMs?: number;           // default 5000
}

await send("team only", { channel: "group", groupId: "g1" });
Copy

send() rejects if no host handler is wired, if the host returns an error, or if it times out (default 5s). Wrap calls in try/catch.

Replying

reply() is send() with replyTo pre-filled:

import { reply } from "@urth/metatell-sdk/chat";

await reply(message.id, "got it");
Copy

Mentions

Mentions are encoded in message text as [@display](sessionId). Use parseMentions() to extract them:

import { parseMentions } from "@urth/metatell-sdk/chat";

const mentions = parseMentions("hi [@Alice](a1b2c3d4) and [@Bob](e5f6a7b8)");
// [{ sessionId, display, start, end }, ...]
Copy

Each Mention carries the sessionId, the display text, and the start/end offsets within the original string, so you can render them as links or chips.

Related

• Remote Users to resolve a sessionId to a user.