Plugin API Reference

TojuClientPluginApi is the object passed to a plugin activation context. The runtime freezes the API object before passing it to plugin code.

This page is the compact map. Use the focused API pages for concrete copy-paste examples with literal input data.

Focused API Pages

Activation Types

interface TojuPluginDisposable {
  dispose: () => void;
}

interface TojuPluginActivationContext {
  api: TojuClientPluginApi;
  manifest: TojuPluginManifest;
  pluginId: string;
  subscriptions: TojuPluginDisposable[];
}

interface TojuClientPluginModule {
  activate?: (context: TojuPluginActivationContext) => Promise<void> | void;
  deactivate?: (context: TojuPluginActivationContext) => Promise<void> | void;
  onPluginDataChanged?: (context: TojuPluginActivationContext, event: unknown) => Promise<void> | void;
  onServerRequirementsChanged?: (context: TojuPluginActivationContext, snapshot: PluginRequirementsSnapshot) => Promise<void> | void;
  ready?: (context: TojuPluginActivationContext) => Promise<void> | void;
}

Profiles

interface PluginApiProfileUpdate {
  description?: string;
  displayName: string;
}

interface PluginApiAvatarUpdate {
  avatarHash: string;
  avatarMime: string;
  avatarUrl: string;
}

Method	Capability	Description
`profile.getCurrent()`	`profile.read`	Returns the current `User` or `null`.
`profile.update(profile)`	`profile.write`	Updates display name and optional description.
`profile.updateAvatar(avatar)`	`profile.write`	Updates avatar URL, MIME type, and hash metadata.

Users and Roles

Method	Capability	Description
`users.getCurrent()`	`users.read`	Returns current `User` or `null`.
`users.list()`	`users.read`	Returns known users.
`users.readMembers()`	`users.read`	Returns active room members.
`users.setRole(userId, role)`	`roles.manage`	Updates a user's role.
`users.kick(userId)`	`users.manage`	Kicks a user.
`users.ban(userId, reason?)`	`users.manage`	Bans a user with optional reason.
`roles.list()`	`roles.read`	Returns room roles.
`roles.setAssignments(assignments)`	`roles.manage`	Replaces role assignments.

Server

interface PluginApiServerSettingsUpdate {
  description?: string;
  isPrivate?: boolean;
  maxUsers?: number;
  name?: string;
  password?: string;
  topic?: string;
}

interface PluginApiPluginUserRequest {
  avatarUrl?: string;
  displayName: string;
  id?: string;
}

Method	Capability	Description
`server.getCurrent()`	`server.read`	Returns the current `Room` or `null`.
`server.registerPluginUser(request)`	`users.manage`	Adds a plugin-owned user and returns its id.
`server.updatePermissions(permissions)`	`server.manage`	Updates partial room permissions.
`server.updateSettings(settings)`	`server.manage`	Updates room settings.

Channels

interface PluginApiChannelRequest {
  id?: string;
  name: string;
  position?: number;
}

Method	Capability	Description
`channels.list()`	`channels.read`	Returns current room channels.
`channels.select(channelId)`	`channels.read`	Selects a channel.
`channels.addAudioChannel(request)`	`channels.manage`	Adds a voice channel.
`channels.addVideoChannel(request)`	`channels.manage`	Registers a video channel section.
`channels.rename(channelId, name)`	`channels.manage`	Renames a channel.
`channels.remove(channelId)`	`channels.manage`	Removes a channel.

Messages

interface PluginApiMessageAsPluginUserRequest {
  channelId?: string;
  content: string;
  pluginUserId: string;
}

Method	Capability	Description
`messages.readCurrent()`	`messages.read`	Returns current visible messages.
`messages.send(content, channelId?)`	`messages.send`	Sends a message and returns the created `Message`.
`messages.sendAsPluginUser(request)`	`messages.send`	Emits a message from a registered plugin user.
`messages.setTyping(isTyping, channelId?)`	`messages.send`	Broadcasts current typing state for a channel.
`messages.subscribeTyping(handler)`	`messages.read`	Subscribes to peer typing state.
`messages.edit(messageId, content)`	`messages.editOwn`	Edits a plugin message.
`messages.delete(messageId)`	`messages.deleteOwn`	Deletes a plugin message.
`messages.moderateDelete(messageId)`	`messages.moderate`	Performs a moderation delete.
`messages.sync(messages)`	`messages.sync`	Syncs an array of messages into state.

Events

interface PluginApiEventSubscription {
  eventName: string;
  handler: (event: PluginEventEnvelope) => void;
}

interface PluginEventEnvelope<TPayload = unknown> {
  emittedAt?: number;
  eventId?: string;
  eventName: string;
  payload: TPayload;
  pluginId: string;
  serverId: string;
  sourcePluginUserId?: string;
  sourceUserId?: string;
  type: 'plugin_event';
}

Method	Capability	Description
`events.publishServer(eventName, payload)`	`events.server.publish`	Sends a declared plugin event through the signaling server.
`events.subscribeServer(subscription)`	`events.server.subscribe`	Subscribes to a declared server plugin event.
`events.publishP2p(eventName, payload)`	`events.p2p.publish`	Sends a declared plugin event over peer paths.
`events.subscribeP2p(subscription)`	`events.p2p.subscribe`	Registers a P2P event subscription.

Message Bus

interface PluginApiMessageBusEnvelope {
  channelId?: string;
  eventId: string;
  messages?: Message[];
  payload?: unknown;
  pluginId: string;
  roomId: string;
  sentAt: number;
  sourcePeerId?: string;
  sourceUserId?: string;
  topic: string;
}

interface PluginApiMessageBusLatestRequest {
  channelId?: string;
  includeDeleted?: boolean;
  limit?: number;
  sinceTimestamp?: number;
  targetPeerId?: string;
  topic?: string;
}

interface PluginApiMessageBusPublishRequest extends PluginApiMessageBusLatestRequest {
  includeLatestMessages?: boolean;
  includeSelf?: boolean;
  payload?: unknown;
  topic: string;
}

interface PluginApiMessageBusSubscription {
  channelId?: string;
  handler: (event: PluginApiMessageBusEnvelope) => void;
  latestMessageLimit?: number;
  replayLatest?: boolean;
  topic?: string;
}

Method	Capability	Description
`messageBus.publish(request)`	`events.p2p.publish`, optionally `messages.read`	Publishes a plugin-bus event, optionally including latest messages.
`messageBus.sendLatestMessages(request?)`	`events.p2p.publish` and `messages.read`	Sends a latest-message snapshot.
`messageBus.subscribe(subscription)`	`events.p2p.subscribe`, optionally `messages.read`	Subscribes to plugin-bus events, optionally replaying latest messages.

P2P and Media

interface PluginApiAudioClipRequest {
  volume?: number;
  url: string;
}

interface PluginApiCustomStreamRequest {
  label?: string;
  stream: MediaStream;
}

Method	Capability	Description
`p2p.connectedPeers()`	`p2p.data`	Returns connected peer ids.
`p2p.broadcastData(eventName, payload)`	`p2p.data`	Broadcasts plugin data.
`p2p.sendData(peerId, eventName, payload)`	`p2p.data`	Sends plugin data targeted to a peer.
`media.playAudioClip(request)`	`media.playAudio`	Plays an audio URL at optional volume.
`media.addCustomAudioStream(request)`	`media.addAudioStream`	Contributes an audio `MediaStream`.
`media.addCustomVideoStream(request)`	`media.addVideoStream`	Registers a video `MediaStream` contribution.
`media.setInputVolume(volume)`	`audio.volume`	Sets local input volume.
`media.setOutputVolume(volume)`	`audio.volume`	Sets local output volume.

Storage

Method	Capability	Description
`clientData.read(key)`	`storage.local`	Reads async plugin-local data.
`clientData.write(key, value)`	`storage.local`	Writes async plugin-local data.
`clientData.remove(key)`	`storage.local`	Removes async plugin-local data.
`serverData.read(key)`	`storage.serverData.read`	Reads local per-user/per-server data.
`serverData.write(key, value)`	`storage.serverData.write`	Writes local per-user/per-server data.
`serverData.remove(key)`	`storage.serverData.write`	Removes local per-user/per-server data.
`storage.get(key)`	`storage.local`	Legacy synchronous local read.
`storage.set(key, value)`	`storage.local`	Legacy synchronous local write.
`storage.remove(key)`	`storage.local`	Legacy synchronous local remove.

UI Contributions

interface PluginApiActionContribution {
  icon?: string;
  label: string;
  run: () => Promise<void> | void;
}

interface PluginApiPageContribution {
  label: string;
  path: string;
  render: () => HTMLElement | string;
}

interface PluginApiPanelContribution {
  label: string;
  order?: number;
  render: () => HTMLElement | string;
}

interface PluginApiSettingsPageContribution {
  label: string;
  order?: number;
  render: () => HTMLElement | string;
  settingsKey?: string;
}

interface PluginApiChannelSectionContribution {
  label: string;
  order?: number;
  type?: 'audio' | 'custom' | 'video';
}

interface PluginApiEmbedRendererContribution {
  embedType: string;
  render: (payload: unknown) => HTMLElement | string;
}

interface PluginApiDomMountRequest {
  element: HTMLElement;
  position?: InsertPosition;
  target: Element | string;
}

Method	Capability	Description
`ui.registerAppPage(id, contribution)`	`ui.pages`	Adds a plugin app page.
`ui.registerSettingsPage(id, contribution)`	`ui.settings`	Adds a plugin settings page.
`ui.registerSidePanel(id, contribution)`	`ui.sidePanel`	Adds a side panel.
`ui.registerChannelSection(id, contribution)`	`ui.channelsSection`	Adds a channel section.
`ui.registerComposerAction(id, contribution)`	`ui.pages`	Adds a composer action.
`ui.registerProfileAction(id, contribution)`	`ui.pages`	Adds a profile action.
`ui.registerToolbarAction(id, contribution)`	`ui.pages`	Adds an action tile to the server side panel View plugins menu.
`ui.registerEmbedRenderer(id, contribution)`	`ui.embeds`	Adds an embed renderer.
`ui.mountElement(id, request)`	`ui.dom`	Mounts plugin-owned DOM into a target element or selector.

Context and Logger

Method	Capability	Description
`context.getCurrent()`	None	Reads current user, server, active text channel, and active voice channel.
`logger.debug(message, data?)`	None	Writes a debug plugin log entry.
`logger.info(message, data?)`	None	Writes an info plugin log entry.
`logger.warn(message, data?)`	None	Writes a warning plugin log entry.
`logger.error(message, data?)`	None	Writes an error plugin log entry.

Focused API Pages​

Activation Types​

Profiles​

Users and Roles​

Server​

Channels​

Messages​

Events​

Message Bus​

P2P and Media​

Storage​

UI Contributions​

Context and Logger​