OpenMax
Free Trial

Overview

What a plugin is, how to install one, which plugins you get by default, and the three kinds of plugins by where they plug into the UI.

Overview

A plugin adds a piece of functionality to the chat UI without changing the components themselves. The composer's @ mentions and # work-item references are two plugins: each brings its own trigger, candidate panel, toolbar button and data sent with the message, and declares which capabilities it needs from the host.

Kinds of plugins

Plugins come in three kinds, by where they plug into the UI:

Kind Where it plugs in What it is for Status
Composer plugins The composer at the bottom of the thread Triggers and candidate panels, toolbar buttons, content inserted into the composer, structured data sent with the message Available
Message-display plugins Messages in the thread Drawing a kind of message with your own component, such as interactive cards or polls Available
Message-action plugins The "More" menu or action bar of each message Adding an action, such as "Turn into a task" Planned

Composer plugins

One composer plugin can do several things at once: respond to a trigger and open a candidate panel, put a button on the toolbar, insert a block of content into the composer, and send structured data with the message. See Composer plugins.

Message-display plugins

Claims a kind of message (by message.type) and draws its body with its own component. Interactive cards are one: the card plugin cardRenderer claims CARD messages, is skipped when the host has no cards capability, and then cards are drawn read-only. A plugin can hand events to the app with emit. See Message-display plugins.

Message-action plugins

Planned

Add an item to each message's "More" menu, optionally also to the action bar, such as turning a message into a task. Define it with defineMessageAction and install it through messageActions on ChatProvider:

to-task-action.tsx

import { defineMessageAction } from "@openmaxai/chat/message-thread";
import { ListTodo } from "lucide-react";

export const toTaskAction = defineMessageAction({
  id: "to-task",
  label: (locale) => (locale.startsWith("en") ? "Turn into a task" : "转成任务"),
  icon: ListTodo,
  requiredPorts: ["workItems"],
  isAvailable: (message) => message.type === "TEXT",
  onSelect: async (message, { notify }) => {
    await createTaskFrom(message);
    notify("success", "Turned into a task");
  },
});

<ChatProvider host={host} messageActions={[toTaskAction]}>{/* … */}</ChatProvider>;
Field (ChatMessageAction) Type Required Description
id string Yes Unique; clashing with a built-in action (copy, react, reply, edit, recall, pin) or another plugin throws when the set is assembled
label (locale: string) => string Yes Text of the menu item and button, also its accessible name
icon ComponentType<{ className?: string }> No Icon; required when placed on the bar
requiredPorts readonly string[] No Host capabilities it needs; missing any one skips it, as with composer plugins
isAvailable (message: ChatMessage, ctx: ChatMessageActionContext) => boolean No Whether it shows on this message; without it, it shows on every sent, unrecalled message. Called during render, so do not throw
onSelect (message: ChatMessage, ctx: ChatMessageActionContext) => void | Promise<void> Yes What it does. The item is disabled until the returned Promise settles; a rejection shows the error's message
placement "menu" | "bar" No Default "menu". "bar" also puts it on the action bar, before the "More" button
destructive boolean No Shown in red, after the menu's separator

ChatMessageActionContext has host (the current host), conversation, currentUserId, locale and notify (the same as host.attention.notify).

  • In the menu, plugin actions come after the built-in ones and before the separator, in the order of messageActions.
  • Without messageActions there are no plugin actions. It is passed separately from plugins, which holds composer plugins only.
  • In read-only conversations plugin actions still follow isAvailable; whether to hide in read-only conversations is the plugin's call (ctx.conversation).

Installing plugins

Plugins go to ChatProvider together with the host, through the plugins prop:

app.tsx

import { COMPOSER_PLUGINS } from "@openmaxai/chat/composer";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { emojiShortcodePlugin } from "./emoji-shortcode-plugin";

// Without plugins: the default plugins are installed
<ChatProvider host={host}>{/* … */}</ChatProvider>;

// The default plugins plus one of your own
<ChatProvider host={host} plugins={[...COMPOSER_PLUGINS, emojiShortcodePlugin]}>
  {/* … */}
</ChatProvider>;
  • Without plugins you get the default plugins, COMPOSER_PLUGINS.
  • With it you get exactly the plugins you pass. To keep the defaults, put them in the same array as your own; the order sets the order of the toolbar buttons.
  • The whole chat uses one plugin set. The list can be written inline in JSX: the SDK compares plugins by id and does not rebuild the editor while the ids stay the same (so swapping a plugin object under the same id has no effect).
  • plugins holds composer plugins. Message-action plugins are installed through messageActions Planned; see Message-action plugins. Message-display plugins are installed through messageRenderers; see Message-display plugins · Installing.

How emojiShortcodePlugin is written: see Write a composer plugin.

Plugins whose capabilities are missing are skipped

Each plugin declares the capabilities it needs in requiredPorts. If the host lacks any of them, the SDK does not install that plugin: nothing throws, the other plugins and the composer work as usual, and you don't filter anything yourself. A host without workItems, for example, has no # trigger or # button in the composer, while @ still works. If the host changes at runtime, the plugins are picked again. See Capabilities · Composer plugins.

Default plugins

COMPOSER_PLUGINS holds the built-in plugins, in this order:

Plugin id What it does requiredPorts
emoji Planned Emoji button: opens an emoji panel and inserts the picked emoji as text. There whether the composer is collapsed or expanded none
mention @ mentions: inserts a mention chip and sends structured mentions identity, i18n
work-reference # work-item references: searches projects and issues and inserts a reference chip workItems

identity and i18n are required capabilities, so every host has @; workItems is optional; the emoji button needs none. Details of each plugin are in Built-in plugins.

Next steps

  • Composer plugins: Triggers, toolbar buttons, content nodes, send data and required capabilities.
  • Built-in plugins: @ mentions and # work-item references: what they do, what they need, what they send.
  • Write a composer plugin: Write a plugin from scratch and install it next to the defaults.
  • Message-display plugins: Draw a kind of message with your own component: claiming rules, installing, sending events.