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
messageActionsthere are no plugin actions. It is passed separately fromplugins, 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
pluginsyou 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).
pluginsholds composer plugins. Message-action plugins are installed throughmessageActionsPlanned; see Message-action plugins. Message-display plugins are installed throughmessageRenderers; 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.
