OpenMax
Free Trial

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.