Widget SDK Reference

@nexvio-ai/widget-js is the official client library for embedding the ChatDrift agent. It ships two custom elements and matching React components, and runs entirely in the browser — no server-side setup needed beyond identity verification.

Installation

npm install @nexvio-ai/widget-js
# or
pnpm add @nexvio-ai/widget-js
# or
yarn add @nexvio-ai/widget-js

Two embed modes

Use <nexvio-agent> when you want the chat embedded in a page section. Use <nexvio-chat-bot> when you want the familiar floating button in the corner of every page.

Quickstart

Inline widget (React)

import { NexvioWidget } from "@nexvio-ai/widget-js/react"

export function SupportPanel() {
  return (
    <NexvioWidget
      options={{
        publicKey: "pk_...",
        context: {
          locale: "en",
        },
      }}
    />
  )
}

Floating launcher (React)

import { NexvioChatbot } from "@nexvio-ai/widget-js/react"

export function SupportChat() {
  return (
    <NexvioChatbot
      options={{
        publicKey: "pk_...",
        position: "bottom-right",
        defaultOpen: false,
      }}
    />
  )
}

Script tag (floating launcher)

<script>
  window.nexvioConfig = {
    publicKey: "pk_..."
  }
</script>
<script src="https://app.nexvio.ai/api/agent.js" async></script>

<nexvio-chat-bot></nexvio-chat-bot>

NexvioWidgetOptions

These options apply to both <nexvio-agent> and <nexvio-chat-bot>.

Appearance

interface NexvioWidgetAppearance {
  colorScheme?: "light" | "dark"
}

Visitor context

Passes unverified visitor metadata to the agent. For verified identity (logged-in users), use identity instead.

interface VisitorContext {
  name?: string
  email?: string
  phone?: string
  locale?: string
  timezone?: string
  externalId?: string
  props?: Record<string, unknown>
}

Start screen

interface StartScreenConfig {
  greeting?: string
  prompts?: Array<{
    label: string
    prompt: string
  }>
}

NexvioChatbotOptions

<nexvio-chat-bot> / <NexvioChatbot> accepts all NexvioWidgetOptions plus:

Public methods

Obtain a reference to the element before calling methods.

React

import { useRef } from "react"
import { NexvioChatbot, type NexvioChatbotElement } from "@nexvio-ai/widget-js/react"

export function Chat() {
  const ref = useRef<NexvioChatbotElement>(null)

  return (
    <>
      <NexvioChatbot ref={ref} options={{ publicKey: "pk_..." }} />
      <button onClick={() => ref.current?.open()}>Open chat</button>
    </>
  )
}

Custom element

const widget = document.querySelector("nexvio-chat-bot")
widget.open()

Method reference

React hooks

useNexvioWidget

import { useNexvioWidget } from "@nexvio-ai/widget-js/react"

function MyWidget() {
  const { ref, identify, resetUser } = useNexvioWidget()

  return <nexvio-agent ref={ref} />
}

Returns { ref, setElement, identify, resetUser }.

useNexvioChatbot

import { useNexvioChatbot } from "@nexvio-ai/widget-js/react"

function MyChat() {
  const { ref } = useNexvioChatbot()

  return <nexvio-chat-bot ref={ref} />
}

Returns { ref, setElement }.

Client tools

Client tools let your server-side agent call JavaScript functions running in the user's browser — for example, to navigate to a page, open a modal, or read local state.

import { NexvioWidget } from "@nexvio-ai/widget-js/react"
import { z } from "zod"

<NexvioWidget
  options={{
    publicKey: "pk_...",
    client: {
      tools: [
        {
          name: "navigate",
          description: "Navigate the user to a URL in the current app",
          parameters: z.object({ url: z.string().url() }),
          execute: async ({ url }) => {
            window.location.href = url
            return { navigated: true }
          },
        },
      ],
    },
  }}
/>

Tool schemas are sent to the agent as part of the conversation context. When the agent calls a tool, the SDK executes execute() in the browser and returns the result to the agent automatically.

Events

Pass an onEvent callback to receive lifecycle and interaction events from the widget.

<NexvioWidget
  options={{
    publicKey: "pk_...",
    onEvent: (event) => {
      console.log(event.type, event)
    },
  }}
/>

Identity verification

See the dedicated Identity Verification guide for server-side JWT and HMAC token generation, and how to call identify() from the SDK.