Reference

SDK Reference

Provider, hooks, surfaces, runtime data.

ModelNexProvider Runtime Data Contract Hooks Review and Re-Teach UI Surfaces Integration Guidance

ModelNexProvider

ModelNexProvider is required. Mount it above routed product content.

tsx

<ModelNexProvider
  websiteId="your-website-id"
  userProfile={{
    userId: currentUser.id,
    type: currentUser.role,
    isNewUser: currentUser.isNewUser,
  }}
>
  <App />
</ModelNexProvider>

Prop	Type	Description
`websiteId` Required	`string`	Project identifier for the ModelNex integration.
`userProfile`	`object`	Current user identity and audience fields used for targeting and progress state.

Dev tooling is enabled only through a browser-injected __MODELNEX_DEV_MODE_KEY__ value that the SDK verifies for the active websiteId.

Runtime Data Contract

userProfile.userId should be stable and persistent.
userProfile.type should match the audiences you plan to target.
userProfile.isNewUser should reflect your actual first-use logic.
always flows do not need extra trigger-specific fields.

Targeting accuracy

Complete userProfile data makes prompts, workflows, and resume behavior much more reliable.

Hooks

useRunCommand triggers command execution from a custom UI.
useUIState syncs local interface state with the assistant.
useVoice handles speech-to-text and continuous listening.
useOnboardingPlayback powers workflow playback.
useRecordingMode exposes authoring tools for internal users, including recording and step re-teach during preview.

tsx

import { useRunCommand } from '@modelnex/sdk'

function MyAssistant() {
  const runCommand = useRunCommand()

  async function handleSend(input: string, signal?: AbortSignal) {
    return runCommand(input, signal)
  }

  return null
}

Review and Re-Teach

During internal preview sessions, the SDK can pause an in-progress step and capture a corrected recording for that step. When the correction is applied, Portal saves it into the current draft and shows it as the next draft version.

Access control

Keep recording and re-teach access restricted to trusted reviewers. These tools are for authoring and QA, not for customer-facing production use.

UI Surfaces

Primary

ModelNexChatBubble

Unified assistant and workflow surface for most integrations.

Advanced

Custom UI + hooks

Use SDK hooks when you need a bespoke shell or a deeply branded interface.

agentName controls the header label.
appName is used in onboarding copy and narration.
welcomeMessage defines the initial assistant message.
theme overrides colors and sizing.
placeholder sets input placeholder text.

Integration Guidance

Mount the provider above routed product content.
Add data-testid to important interactive targets before recording flows.
Only distribute __MODELNEX_DEV_MODE_KEY__ to trusted operators and inject it from a controlled browser context.
Re-test forced runs after releases that change routes, labels, or DOM structure.

View all guides Previous: Chat Bubble