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 = {
    position: "bottom-right"
  }
</script>
<script src="https://chatdrift.com/api/agent.js" async></script>

<nexvio-widget id="pk_..."></nexvio-widget>

The id attribute is your agent's public key. For each <nexvio-widget id="..."> tag, the script adds a <nexvio-chat-bot> launcher to the page and applies the options from window.nexvioConfig (any NexvioChatbotOptions except publicKey, which comes from the tag's id). Add mode="open" to the tag to open the chat panel on load. window.nexvioConfig is not read by <nexvio-chat-bot> or <nexvio-agent> elements you create yourself — call setOptions({ publicKey: "pk_..." }) on those.

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({ publicKey: "pk_..." })

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

Takes the same NexvioWidgetOptions as the component and returns { ref, setElement, identify, resetUser }.

useNexvioChatbot

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

function MyChat() {
  const { ref } = useNexvioChatbot({ publicKey: "pk_..." })

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

Takes the same NexvioChatbotOptions as the component and 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 events emitted from inside the widget. Each event is { name, detail }.

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

Common event names include session.started, session.ended, message.submitted, starter.used, identity.verified, identity.reset, visitor.updated, theme.changed, and view.change.

The same events are also dispatched as DOM CustomEvents on the element, so you can listen with addEventListener instead of (or in addition to) onEvent:

const widget = document.querySelector("nexvio-chat-bot")
widget.addEventListener("nexvio.ready", () => console.log("Widget ready"))
widget.addEventListener("chatbot.opened", () => console.log("Chat opened"))

Identity verification

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