@oatbox/widget

React + vanilla JS SDK for the Oatbox embeddable agent widget.

For most installs you don't need this package — just paste the script tag from your dashboard's install page. Use @oatbox/widget when you want bundler-resolved imports, TypeScript types, or to mount the widget inside a React tree.

Install

npm install @oatbox/widget

React is an optional peer dependency. If you only use the vanilla API, you can install without React.

Quick start — vanilla JS

import { init } from "@oatbox/widget"

init({ agentId: "YOUR_AGENT_ID" })

Quick start — React

import { OatboxProvider, useOatbox } from "@oatbox/widget/react"

export function App() {
  return (
    <OatboxProvider agentId="YOUR_AGENT_ID">
      <Page />
    </OatboxProvider>
  )
}

function Page() {
  const { isReady, open, close, toggle } = useOatbox()
  return <button disabled={!isReady} onClick={open}>Chat with us</button>
}

API

Vanilla — @oatbox/widget

| Export | Signature | Notes | | --- | --- | --- | | init(config) | (config: OatboxConfig) => Promise<void> | Loads the widget script and resolves once ready. | | identify(user) | (user: OatboxUser) => void | Push or update the current user identity. | | open() / close() / toggle() | () => void | Control the chat panel. | | destroy() | () => void | Remove the widget from the page. | | isReady() | () => boolean | True after the loader script has booted. |

React — @oatbox/widget/react

| Export | Signature | Notes | | --- | --- | --- | | <OatboxProvider agentId user? host? onReady?> | React component | Mounts the widget on first render, unloads on unmount. | | useOatbox() | () => { isReady, open, close, toggle } | Read widget state + controls from the surrounding <OatboxProvider>. | | useOatboxIdentify() | () => (user: OatboxUser) => void | Update identity from any descendant. |

Types

import type { OatboxConfig, OatboxUser, OatboxControls } from "@oatbox/widget"

Configuration

init({
  agentId: "YOUR_AGENT_ID",        // required
  host: "https://cdn.oatbox.ai",   // override loader origin (e.g. self-hosted)
  user: {                          // optional initial identity
    userId: "user_123",
    email: "[email protected]",
    name: "Jane Doe",
    company: "Acme Co",
  },
  onReady: () => console.log("widget ready"),
})

Peer dependencies

React 18+ and React DOM 18+ are listed as optional peer dependencies. The vanilla entry (@oatbox/widget) does not import React, so consumers who only use the vanilla API can install without it. The @oatbox/widget/react subpath does import React — install it there.

Links

• Docs: https://oatbox.ai/docs
• Changelog: CHANGELOG.md
• Issues: https://github.com/oatbox/oatbox/issues

Security

This package does not execute any code at install time. It has zero transitive runtime dependencies (React is an optional peer for @oatbox/widget/react).

Report security issues privately to [email protected] — see the Security Policy. We respond within 24 hours.

License

MIT