Start here

Quickstart

Install, mount, and verify a first run.

What You Build Before You Begin Install the SDK Mount the Provider Render a Surface Verify the Integration Common Mistakes

What You Build

A working provider setup plus a chat surface connected to your real user and feature data.

Outcome: Assistant running in your app shell.
Time: About 10 minutes.
Next: Continue with Workflow.

Before You Begin

You need a React 18+ app.
Required: create a project in the ModelNex portal to generate a websiteId.
For the best targeting, expose a stable authenticated user ID in your app shell.

Why identity matters

userProfile.userId lets workflows track completion correctly and avoids repeat onboarding.

Install the SDK

Install the SDK in the same app that renders the product UI.

bash

npm install @modelnex/sdk react react-dom zod

Mount the Provider

Mount ModelNexProvider above routed content so the assistant and workflows survive route changes.

tsx

import { ModelNexProvider, ModelNexChatBubble } from '@modelnex/sdk'

export default function AppShell() {
  return (
    <ModelNexProvider
      websiteId="your-website-id"
      userProfile={{ userId: 'user-123' }}
    >
      <Routes />
      <ModelNexChatBubble appName="My Product" />
    </ModelNexProvider>
  )
}

Why this shape matters

The top-level provider keeps assistant state alive while users move through your product.

Render a Surface

Most teams start with ModelNexChatBubble. It supports general assistant chat and workflow playback from one surface.

Assistant chat: natural-language support and commands.
Workflow mode: progress-oriented activation guidance with explicit handoff to the user.

Verify the Integration

Load your app and confirm the bubble renders.
Inject a valid browser dev mode key and confirm the backend verification succeeds before you try to record.
Run a forced preview with ?modelnex_test_workflow=FLOW_ID.
Verify targets resolve on the real recorded routes.

Success check

If you can trigger a forced workflow run end-to-end, the integration is ready for real content.

Common Mistakes

Mounting the provider too low: wrap your routing logic so the assistant does not reset on navigation.
Fragile UI targeting: add data-testid to important controls before recording flows.
Missing dev-mode access: inject a valid __MODELNEX_DEV_MODE_KEY__ value in the browser before opening the recorder.

Next: Workflow.

View all guides Next: SDK Configuration