Spaces and Users

A space is a conversation — a DM, a group chat, a terminal session. A user is a participant identified by a platform-specific ID. Both carry a __platform tag so the narrowing functions from platform narrowing can recover their platform-specific shapes.

Space

Every exposes the same interface regardless of platform:

Space

Member	Description
`readonly __platform: string`
`add(users: MemberInput): Promise<void>`	Add members to the current chat. Sugar for `send(addMember(users))`. Accepts a single `User` or id string, or an array of either — batches land in one provider call. Fire-and-forget.
`avatar(input: string \| URL, options?: { mimeType?: string; }): Promise<void>`	Set or clear the current chat’s avatar (group icon). Sugar for `send(avatar(input, options?))`.
`avatar(input: Buffer, options: { mimeType: string; }): Promise<void>`
`edit(message: Message \| undefined, newContent: ContentInput): Promise<void>`	Rewrite a previously-sent outbound message. Sugar for `send(edit(newContent, message))`. Accepts `Message \| undefined` so `send` results chain without narrowing; an undefined target throws.
`getAvatar(): Promise<AvatarData \| undefined>`	Download the current chat avatar (group icon). Resolves `undefined` when the chat has none. The result round-trips into the setter: `space.avatar(res.data, { mimeType: res.mimeType })`.
`getDisplayName(): Promise<string \| undefined>`	Read the current chat’s display name (group/chat title). Resolves `undefined` when the chat has none — an unnamed group, or a 1:1 chat on a platform that stores no title for DMs. Round-trips into `space.rename()`.
`getMembers(): Promise<User[]>`	List the chat’s current participants, excluding the agent’s own account where the platform can identify it. Each entry is a `User` tagged with `__platform`; `id` is the user’s canonical platform handle (the same format `space.create` accepts), so results feed straight back into `add()` / `remove()` / `space.create()`. Platform extras (e.g. iMessage’s `address`/`country`/`service`) ride along untyped — use the platform instance’s `getMembers(space)` for typed extras.
`getMessage(id: string): Promise<Message \| undefined>`	Look up a message in this space by its id. Returns `undefined` if the platform has no way to resolve the id (e.g. cache miss with no by-id SDK fallback). Used to materialize a `Message` for APIs that require one, such as `reaction()`.
`readonly id: string`
`leave(): Promise<void>`	Leave the current chat with the agent’s own account. Sugar for `send(leaveSpace())`. Fire-and-forget.
`read(message: Message): Promise<void>`	Mark the conversation as read up to `message`, surfacing a read receipt to the sender where the platform supports one. Sugar for `send(read(message))`. Fire-and-forget; only inbound messages can be marked read.
`remove(users: MemberInput): Promise<void>`	Remove members from the current chat. Sugar for `send(removeMember(users))`. Accepts the same input shapes as `add`. Fire-and-forget.
`rename(displayName: string): Promise<void>`	Rename the current chat. Sugar for `send(rename(displayName))`.
`responding<T>(fn: () => T \| Promise<T>): Promise<T>`
`send(content: ReactionBuilder): Promise<(Message<string, AgentSender> & { content: Reaction; }) \| undefined>`	A reaction send resolves to the reaction Message (`content` narrowed to `Reaction`) — the handle to `unsend()` later. Listed before the general overload so `send(reaction(...))` picks it; every other `ContentBuilder` fails the `ReactionBuilder` shape and falls through.
`send(content: ContentInput): Promise<Message<string, AgentSender> \| undefined>`
`send(...content: [ContentInput, ContentInput, ...ContentInput[]]): Promise<Message<string, AgentSender>[]>`
`startTyping(): Promise<void>`
`stopTyping(): Promise<void>`
`unsend(message: Message \| undefined): Promise<void>`	Retract a previously-sent outbound message. Sugar for `send(unsend(message))`. Accepts `Message \| undefined` so `send` results chain without narrowing; an undefined target throws.

Provider-specific constraints surface as an .

for await (const [space, message] of app.messages) {
  await space.send("Got it.");
}

User

Every has a platform-specific ID and platform tag.

User

Field	Description
`readonly __platform: string`
`readonly id: string`
`readonly kind?: "agent"`

Resolve a user from a platform-specific identifier through a narrowed platform instance:

import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(app);
const alice = await im.user("+15551234567");

The returned user may include additional platform-specific fields when the provider defines a user.schema.

Typing indicators

Manual

await space.startTyping();
// ... do work ...
await space.stopTyping();

These are sugar for space.send(typing("start")) and space.send(typing("stop")) — see Typing indicators for the canonical form.

Automatic with `responding`

responding is the recommended pattern. It guarantees the typing indicator is cleared even if the inner function throws:

await space.responding(async () => {
  const result = await generateResponse(message);
  await space.send(result);
});

The helper is also available on the app itself:

await app.responding(space, async () => {
  await space.send("Thinking...");
});

Creating a space

To start a new conversation, use platform narrowing to get a platform instance, then call space.create(...) with the users:

const im = imessage(app);
const alice = await im.user("+15551111111");
const bob = await im.user("+15552222222");

// DM
const dm = await im.space.create(alice);

// Group
const group = await im.space.create([alice, bob]);

await group.send("Welcome to the group.");

To look up an existing conversation by its platform ID, use space.get(id):

const existing = await im.space.get("any;-;+15551111111");
await existing.send("Hello again.");

The returned space is the platform-specific type — so you can read extra fields like type: "dm" | "group" on iMessage — but it also satisfies the generic interface, so send(), startTyping(), and friends are always available.

Get started

Core concepts

Content

Providers

Advanced

Integrations

Best Practices

Troubleshooting

Spaces and Users

Space

User

Typing indicators

Manual

Automatic with `responding`

Creating a space

​Space

​User

​Typing indicators

​Manual

​Automatic with responding

​Creating a space

Space

User

Typing indicators

Manual

Automatic with `responding`

Creating a space