Skip to content
Sup

SupChat

The SupChat object represents a chat or conversation in Sup. It provides information about the chat and methods for storing chat-specific data.

Example Chat
SupChat: {
  "id": "cm37h4ky3000108mego5udiz4",
  "title": "Ribbit Chat",
  "type": "GROUP"
}

Properties

id

type: string

The unique identifier for the chat.

title

type: string

The current title or name of the chat.

type

type: "DIRECT" | "GROUP" | "CHANNEL" | "SOLOCHAT" | "THREAD" | "PAGE"

The type of chat:

  • DIRECT: One-on-one conversation between two users
  • GROUP: Group DM with multiple participants
  • CHANNEL: Public channel
  • SOLOCHAT: User’s notebook
  • THREAD: A message’s thread or post comments
  • PAGE: A page post

fs

type: SupFiles

sup.chat.fs.write(
  '/exports/summary.txt',
  sup.file('https://example.com/summary.txt', 'text/plain')
);

File storage for this chat. sup.chat.fs has the same methods as sup.fs, but it does not allow cross-chat access.

Methods

set

type: function(key: string, value: any): void

sup.chat.set("pinnedMessage", "cm37h674y000408mec7b2ae5a");

Sets a key-value pair in the patch’s state, scoped to this chat.

The key can be any string, and the value can be any JSON-serializable object (including Sup classes like SupUser, SupImage, SupMessage, etc.).

Chat-scoped values persist across patch executions and are only accessible when patch running in the same chat.

get

type: function(key: string): any | null

const pinnedMessage = sup.get("pinnedMessage"); // "cm37h674y000408mec7b2ae5a"

Retrieves the value of a key from the chat’s state in this patch.

If the key does not exist, get returns null.

Chat-specific data can be useful for storing game states, chat settings, statistics, or other persistent information that should be available to all participants in the chat.

keys

type: function(): string[]

const keys = sup.chat.keys(); // ["pinnedMessage", "gameState", ...]

Returns an array of all keys stored in this chat’s scoped state.

File Storage

The fs property provides chat-scoped file storage helpers.

fs.write

type: function(path: string, file: string | SupImage | SupAudio | SupVideo | SupFile, options?: { mimeType?: string }): SupImage | SupAudio | SupVideo | SupFile

const image = sup.ai.image.create('retro game over screen');
sup.chat.fs.write('/images/game-over.png', image);

Writes a file into this chat’s storage.

fs.read

type: function(path: string): SupImage | SupAudio | SupVideo | SupFile

const image = sup.chat.fs.read('/images/game-over.png');
return image;

Reads a previously stored file from this chat.

fs.exists

type: function(path: string): boolean

if (sup.chat.fs.exists('/images/game-over.png')) {
  return 'already saved';
}

Checks whether a file or directory exists.

fs.list

type: function(path?: string): { filename?: string; isDirectory: boolean; mimeType?: string; path: string; size?: number; type: "file" | "directory"; url?: string }[]

const files = sup.chat.fs.list('/images');

Lists files and directories in chat storage.

fs.stat

type: function(path: string): { filename: string; isDirectory: false; mimeType: string; path: string; size: number; url: string } | null

const info = sup.chat.fs.stat('/images/game-over.png');

Returns metadata for a stored file, or null if it is missing.

fs.mkdir

type: function(path: string): void

sup.chat.fs.mkdir('/images');

Creates an empty directory in chat storage.

fs.move

type: function(oldPath: string, newPath: string): void

sup.chat.fs.move('/drafts/version-1.png', '/images/final.png');

Moves a file within chat storage.

Users

The users property provides methods for querying participants in the chat.

users.list

type: function(options?: { limit?: number; offset?: number }): SupUser[]

const users = sup.chat.users.list(); // first 100 users
const page2 = sup.chat.users.list({ limit: 50, offset: 50 });

Returns an array of SupUser objects representing the active participants in this chat.

  • limit: Maximum number of users to return (1-500, default: 100)
  • offset: Number of users to skip for pagination (default: 0)

users.count

type: function(): number

const total = sup.chat.users.count();

Returns the total number of active participants in this chat.