Obi SDK

A JavaScript SDK with dynamic content capabilities for integrating Obi into your web applications.

Features

• Assistant interacts through voice and screen share
• DOM analysis allows the assistant to improve context
• Framework-agnostic UI components using Web Components
• Event-based API
• TypeScript support
• Session persistence across page reloads

Configuration Options

The loader accepts the following configuration options:

| Option | Type | Default | Description | | ---------------- | ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | position | string | 'bottom-right' | Position of the widget on the page. Options: 'bottom-right', 'bottom-left', 'bottom-center', 'top-right', 'top-left', 'top-center', 'middle-left', 'middle-right' | | apiKey | string | - | Your Obi API key (required for production) | | user | object | - | User information with id (required), email, first_name, last_name, company (all optional), and metadata (optional) for additional custom fields | | isActive | boolean | true | Whether to show the widget. Set to false to disable the widget for specific users | | linkOnlyAccess | boolean | false | Hide the widget unless accessed via a session link. Perfect for trial periods where only customers with direct links should see the widget | | primaryColor | string | - | Custom primary color for the widget UI (CSS color value) |

Installation

For installation instructions, we recommend using the obi-loader package. This package provides a lightweight loader that will automatically fetch and initialize the full and latest SDK.

Please visit the obi-loader npm package for installation methods and documentation.

Widget Positioning

The widget can be positioned in one of eight positions on the page:

window.obiWidgetConfig = {
  position: "bottom-right", // Options: "bottom-right", "bottom-left", "bottom-center", "top-right", "top-left", "top-center", "middle-left", "middle-right"
  apiKey: "YOUR_API_KEY",
}

Trial Mode / Link-Only Access

The linkOnlyAccess option is perfect for trial periods where you want to control who can see and interact with the widget. When enabled, the widget remains hidden until a session is started via a direct link.

window.obiWidgetConfig = {
  apiKey: "YOUR_API_KEY",
  linkOnlyAccess: true, // Widget only visible when accessed via session link
}

This is ideal for:

• Trial periods where only specific customers should see the widget
• Beta testing with selected users
• Controlled rollouts using session-specific links
• Demo environments where widget access is link-based

When linkOnlyAccess is true:

• Widget is invisible to regular website visitors
• Widget becomes visible only when a session is started (e.g., via URL parameters)
• Once a session ends, the widget returns to hidden state

Session Persistence

The SDK now supports session persistence across page reloads and navigation. If a user refreshes the page or navigates to another page on your site, the session with Obi will be automatically restored when they return, providing a seamless experience.

Key features of session persistence:

• Sessions are stored locally in the browser using a namespaced localStorage implementation
• Session data is automatically cleared after a configurable expiration time (default: 5 minutes)
• When reconnecting, the previous session state is restored, including the current conversation
• Users can manually end a session at any time by using the disconnect option

No additional configuration is required to enable this feature.

Engagement Sessions

The SDK also tracks lightweight engagement sessions per product + onboardee for analytics. A new engagement session starts after 30 minutes of inactivity and is stored in localStorage. You can subscribe to the engagementSessionStarted event and read current values via getEngagementInfo() on the SDK instance (available as window.obi when using the loader).

• Event: engagementSessionStarted with { sessionCount, lastSessionStartAt, lastActivityAt, scopeKey }.
• Accessor: sdk.getEngagementInfo() returns the latest stored info for the current scope.
• Blacklist: URLs matching the product blacklist do not count toward engagement sessions.
• Cross-tab: Duplicate suppression, if enabled, is best-effort within a small window.

See architecture details and examples in STRUCTURE.md under “Engagement Sessions”: STRUCTURE.md#engagement-sessions.

License

SEE LICENSE IN LICENSE.txt