Claritype Embed

Discuss

The Discuss feature brings a specific entity from your app into the conversation. Where passive context is ambient — a continuously updated picture of what the user is viewing — discuss is deliberate: the user points at a chart, a row, a record, and says “tell me about this.”

You might decide to surface this using an “Explain this” button on a chart, a context-menu item on a table row, a sparkle icon next to an anomalous number.

Calling discuss

The useClaritype hook returns the app-level handle used to access discuss. Call it from any component under the provider:

import { useClaritype } from "@claritype/embed-react";

function RevenueChart({ chartId }: { chartId: string }) {
  const { discuss, canDiscuss } = useClaritype();

  return (
    <button
      disabled={!canDiscuss}
      onClick={() =>
        discuss({
          ref: { type: "chart", keys: { id: chartId } },
          prompt: "Explain this chart",
        })
      }
    >
      Explain this
    </button>
  );
}

The handle has two members:

Member	Type	Description
discuss	(options: DiscussOptions) => void	Bring an entity into the conversation.
canDiscuss	boolean	Whether a discuss() call right now would reach a live surface. Reactive.

Specifying the subject

interface DiscussOptions {
  ref: EntityRef;
  snapshot?: Record<string, unknown>;
  prompt?: string;
}

interface EntityRef {
  type: string;
  keys: Record<string, string>;
}

ref — what the user is asking about

ref identifies the entity by type and keys, e.g. { type: "chart", keys: { id: "rev-by-region" } }. Claritype resolves the reference to authoritative data on the backend, using the entity-type mappings configured in your Claritype project.

snapshot — optional client-side data

snapshot attaches data your app already has in hand: computed values, real-time state, anything that would be slow or difficult for Claritype to fetch itself. It’s an arbitrary JSON-serializable object, passed along with the reference as ephemeral input to the conversation.

discuss({
  ref: { type: "chart", keys: { id: "rev-by-region" } },
  snapshot: { series, dateRange, renderedAt: new Date().toISOString() },
});

Use ref for identity and snapshot for state: the reference is what lets the backend fetch fresh, authoritative data, while the snapshot captures what the user is looking at right now.

prompt — optional preset message

Without a prompt, the entity is attached to the user’s message input and the user writes their own question. With a prompt, a message is sent immediately with the message you choose:

discuss({
  ref: { type: "order", keys: { id: orderId } },
  prompt: "Why is this order delayed?",
});

Use prompts for one-click affordances with a clear intent (“Explain this chart”).

What happens on discuss()?

1. The SDK routes the call to the discuss target surface (see below).
2. That surface is revealed: its onReveal prop fires so your app can open the panel (if it isn’t already).
3. The entity (and prompt, if any) lands in the conversation.

So discuss works from a fully closed sidebar. Make sure the target surface passes onReveal.

Which surface receives the discussion request?

If you have multiple Claritype surfaces, discuss() automatically chooses one to route the request to. In order, it looks for:

1. The surface marked discussTarget, if any.
2. Otherwise, the only surface, if exactly one is mounted.
3. Otherwise, a sidebar surface, if one is mounted.

If you mount multiple surfaces, mark exactly one as the discuss target using the discussTarget prop to <ClaritypeSurface>. Marking more than one logs a warning, and the first wins. If no target can be resolved (or none is mounted), discuss() does nothing but logs a console warning.

Ensure the discuss target surface is mounted somewhere that it can always be displayed from wherever discuss is called.

Gating on canDiscuss

useClaritype() also gives you canDiscuss, which is true once the discuss target surface is mounted and connected. It’s a regular reactive value; components re-render when it changes.

You can use this to hide discussion affordances if Claritype isn’t ready:

{canDiscuss && <ExplainButton />}
// or
<button disabled={!canDiscuss} …>

canDiscuss also goes back to false if the target surface unmounts or fails its handshake, so it doubles as a signal for degrading gracefully when Claritype isn’t available.