Custom message rendering
Draw some structured messages yourself with message-display plugins, and customize how text and Markdown display.
Custom message rendering
To draw a kind of structured message yourself, write a message-display plugin; how text and Markdown render is up to the host's render capability. Cards (cws.card.v1) are drawn by the card plugin; their structure, buttons and the cards capability are on Interactive cards.
Structured messages
To draw a kind of message yourself, write a message-display plugin that claims it by message.type and uses matches to accept only your schema:
src/poll-renderer.tsx
import {
type ChatMessageRendererProps,
defineMessageRenderer,
} from "@openmaxai/chat/message-thread";
function PollView({ message, readOnly }: ChatMessageRendererProps) {
const poll = parseMySchema(message); // your own check
return poll ? <PollCard poll={poll} disabled={readOnly} /> : null;
}
export const pollRenderer = defineMessageRenderer({
id: "acme-poll",
types: ["AGENT_STRUCTURED"],
matches: (message) => parseMySchema(message) !== null, // not mine: next plugin or fallback_text
layout: "bare", // brings its own frame, no bubble; leave it out to keep the bubble
View: PollView,
});
With the SDK, install it through messageRenderers on ChatProvider (together with the defaults, CHAT_SDK_MESSAGE_RENDERERS); with @openmaxai/chat directly, through MessageRenderersProvider. See Message-display plugins · Installing. A message no plugin claims shows its fallback_text.
Migrating from renderStructuredMessage / renderCustomMessage
renderStructuredMessage and renderCustomMessage on the host render are removed. Their type on ChatRenderPort is never, so a host that still sets them does not compile; at runtime the message area no longer calls them. Rewrite each as a plugin:
| Before | After |
|---|---|
renderStructuredMessage(message) returns a node when it recognises the message, null otherwise |
The plugin's matches decides, View draws; layout: "bare" (a returned node used to skip the bubble) |
renderCustomMessage(message) (only for types the package does not know; the result sits in a bubble) |
The plugin's matches decides, View draws; leave out layout (bubble by default) |
| Called for every message; you had to be strict yourself | matches is only called for the types in types; built-in types (TEXT etc.) cannot be claimed |
renderCustomMessage came after the message area's own drawing (Agent replies, images and files, text); a message that drawing took first never reached it |
Plugins come before the message area's own drawing: a message your matches claims no longer goes through it, so for example a message with attachments is no longer drawn as images and files. If you relied on that drawing taking some messages first, exclude them in matches yourself. See Order of the message body |
| The host worked out whether the conversation is read-only | View gets readOnly, the same check the composer uses |
| The node used your app's context (query cache, router) | Still works: View is an ordinary component. With the SDK, put your app's QueryClientProvider around ChatProvider and plugins read that client, see When your app uses react-query |
When several plugins claim the same type, the first in installed order wins, so an order you used to write inside one function (check A, then B) becomes the order of the array.
Text and Markdown
render has these members: renderMessageText draws the body of a text message, media captions and system notices; renderMarkdown draws agent replies; renderImage draws images in messages; renderRichText draws text with no message attached, such as a group description; the optional renderMention draws a single @mention outside a message body. Signatures and rules: Host capabilities · render.
The default (createLocalPorts / createChatHost) draws agent replies as Markdown with ChatMarkdown: tables, code blocks, ```mermaid diagrams (loaded only when a reply has one), links, images, mentions and work references. Other text is plain, with links, @mentions and work references.
If you draw mentions yourself, give each mention <span> a data-mention-name (and data-mention-id when known), or copy-pasted mentions stop being real mentions.
Connect Markdown to your app
Links and images in a reply often belong to your app. Pass hooks with the markdown option of createChatHost (or createLocalPorts); each hook you leave out keeps its default.
host.tsx
import { createChatHost } from "@openmaxai/chat-sdk/react";
const host = createChatHost({
adapter,
markdown: {
// In-app routes instead of a new tab; return undefined for everything else.
renderLink: ({ href, label }) =>
href.startsWith(location.origin + "/docs/") ? <InAppLink to={href}>{label}</InAppLink> : undefined,
// artifact:// images and files, all of a reply in one call.
resolveArtifacts: async (uris) => ({ resolved: await myResolve(uris) }),
// Your image viewer; clicking an image passes every image of the reply.
openImageViewer: (slides, index) => viewer.open(slides, index),
},
});
| Hook | Without it |
|---|---|
renderLink |
Every link opens in a new tab |
isAllowedUrl |
Only http(s), mailto, irc(s), xmpp and relative links stay links (javascript:, vbscript: and data: never do, with or without it) |
resolveArtifacts, useResolveArtifacts |
attachments.resolveUrls with the artifact:// prefix removed (retried once, not cached); without that, artifacts show as unavailable |
openImageViewer, renderImageViewer |
The host's viewer port: ports.mediaViewer when given, otherwise the SDK's own viewer; with ports.mediaViewer: null, images are not clickable |
renderImage |
A plain <img> |
labels |
Strings from the kb namespace of i18n |
Work references ([#label](proj://…) / issue://…) do not go through isAllowedUrl or renderLink; the package draws them as chips. To make them clickable, pass ports.workReferences (href + open), used by people's messages and Agent replies alike; see createMarkdownRender. Without it the chips are not clickable.
Turn Markdown off
createChatHost({ adapter, markdown: false }) draws agent replies as plain text with line breaks. To replace the whole render, pass ports.render; createPlainTextRender is the plain-text one, and ChatMarkdown is there if you write your own renderMarkdown.
