Skip to main content
The Salesive Widget system provides embeddable UI components for Salesive storefronts. All widgets use Shadow DOM for complete style isolation and expose a global SalesiveWidget API for programmatic control.
The widget script (https://www.salesive.shop/widget.js) is automatically injected and initialized in all Salesive storefronts. No manual setup is required.

Available widgets

Live Support Chat

Real-time chat widget connecting customers with your sales and support team.

Push Notifications

Subscribe users to real-time order updates and support messages.

PWA Installation

Seamlessly guide users to add your store to their home screen.

Pending Reviews

Slide-out panel for collecting product ratings and reviews from customers.

Live Support Chat

The Live Support Chat widget provides real-time communication between customers and your team. It supports route-based visibility, dark mode, and preserves chat history across page navigations.

Default behavior

The chat widget initializes automatically with these defaults:
  • Appears on all pages (no route filtering)
  • Light mode enabled
  • Shadow DOM isolation active
  • Bundled CSS auto-injected
Use the API methods below to customize behavior at runtime.

Sessions and sign-in

The widget manages the shopper’s chat identity on its own:
  • On first load it creates an anonymous guest session, so a visitor can start chatting without signing in.
  • When the shopper signs in through the storefront, the widget detects it within about a second, reconnects its socket under the real account, and stops showing the sign-in prompt. This also works the other way on logout.
No integration work is required — your theme does not need to reload the page, call unmount()/init(), or notify the widget after login. Conversations started after sign-in are attached to the shopper’s account rather than the guest session.

API methods

The SalesiveWidget global object exposes the following methods for the chat widget:

chat.open()

Open the chat window (expand from bubble).

chat.close()

Close the chat window (minimize to bubble).

chat.toggle()

Toggle the chat window state (open/close).

chat.isOpened (property)

Check if the chat window is currently open. Returns true if open, false otherwise.

chat.hide()

Hide the widget while keeping it mounted. Preserves chat state and history.

chat.show()

Show the widget if it was previously hidden.

chat.toggleVisibility()

Toggle widget visibility. Returns the new visibility state.

chat.setRoutes(routes)

Update the route filtering dynamically.

chat.setDarkMode(enabled)

Toggle or set dark mode. The preference persists across page loads.

chat.isVisible (property)

Read-only property to check current visibility state.

chat.prefill(options)

Prefill the chat input with a text message and/or an image URL. This opens the chat window, switches to the current store’s conversation, and populates the input — ready for the user to review and send.
Use this to create contextual “Contact support” buttons on product or order pages that pre-populate the chat with relevant details.

chat.on(event, handler)

Listen for real-time socket events from the chat system.
Not every message is from a person. Conversation threads also carry system notes (type: "system" — e.g. “Ada took over this conversation”) and call log entries (type: "call"), and both have sender: null. Guard before dereferencing — message.sender?._id, never message.sender._id. Remember that typeof null === "object", so a typeof check alone does not protect you.

chat.emit(event, data)

Send real-time events to the chat system.
Previous global methods hide(), show(), toggle(), setRoutes(), and setDarkMode() are now deprecated but still available for backward compatibility. Please update your integration to use the chat namespace.

setDebugMode(enabled)

Enable or disable debug logging to the browser console.
The current widget version string.

Route filtering

Control which pages display the widget using the routes option. Routes use smart matching:
  • "/" — Matches only the exact homepage, not sub-paths
  • Other routes — Use prefix matching with path boundary detection
Route filtering works with single-page applications. The widget listens to popstate events and intercepts pushState/replaceState calls to detect navigation changes.

Visibility control

Use chat.hide(), chat.show(), and chat.toggleVisibility() to control visibility without losing chat state:
Use hide()/show() instead of unmount()/init() when you want to preserve the user’s chat session and message history.

Dark mode

Dark mode can be toggled dynamically:
Dark mode preference is automatically persisted to localStorage and restored on subsequent page loads.

Shadow DOM isolation

The widget renders inside a Shadow DOM to prevent style conflicts with the host page:
  • Widget styles don’t leak into the host page
  • Host page styles don’t affect the widget
  • Complete encapsulation of the widget UI

Theming

Customize the widget’s primary and secondary brand colors at runtime or before initialization. Set window.SalesiveWidgetConfig before the widget script loads to apply your brand colors on first render with no flash of default colors:
This is the recommended approach for Salesive storefronts that use a custom brand color. It avoids the brief flash of the default blue before the theme is applied.

setTheme(theme)

Update the widget’s theme colors at runtime. Changes apply instantly to all widget surfaces (chat, bubble, notification modal, PWA modal, reviews slider).
Theme values are automatically persisted to localStorage, so custom colors survive page reloads without a flash of default colors.
If an invalid color string is passed, the widget logs a warning and keeps the previous value.

getTheme()

Returns the currently applied theme values.

Theme via init options

You can also pass theme colors in the init() options:

Example: custom controls

Add custom buttons to control the widget programmatically:

Voice calls

When a human agent from the store is online, the chat header shows a call button and the shopper can start a voice call (WebRTC, browser-to-browser — no phone number involved). Incoming calls from the store ring inside the widget the same way.

Call API

Control calls programmatically from theme code via SalesiveWidget.chat.call. Everything is safe to call blind: reads return inert defaults before the widget initializes, and start()/isEnabled() resolve rather than reject. The enabled flag is enforced server-side regardless — this API is UX, not authorization.
Backgrounding mutes the microphone. Mobile operating systems silence microphone capture for a browser tab or installed PWA that is not in the foreground — the call stays connected and incoming audio keeps playing, but the other side cannot hear the shopper until the app is foregrounded again. This is an OS restriction; no web page can override it. Advise shoppers to keep the store open during a call.

Push Notifications

The Push Notifications widget prompts the user to subscribe to order updates and support responses.

API methods

The SalesiveWidget global object exposes the following methods for push notifications:

subscription.open()

Manually trigger the subscription prompt modal.

subscription.getSubscriptionCount()

Get the total number of notifications the user is subscribed to.

PWA Installation

The PWA Installation widget detects if the application is installable and prompts the user to add it to their home screen. It handles both standard browser prompts and custom iOS instructions.

API methods

The SalesiveWidget global object exposes the following methods for PWA installation:

pwa.open()

Manually trigger the installation prompt modal. This is useful for “Install App” buttons in your UI.

pwa.isInstallable()

Check if the PWA is currently installable (i.e., if the browser has fired the beforeinstallprompt event or if it’s an iOS device).

Pending Reviews

The Pending Reviews widget displays a slider containing products from recent orders that need to be reviewed. Users can rate products and leave comments directly within the widget.

Features

  • Auto-show: Automatically appears 10 seconds after page load if there are pending reviews.
  • Frequency control: Once closed, it waits 24 hours before auto-showing again to avoid pestering users.
  • One-by-one flow: Guides users through reviews sequentially.

API methods

The SalesiveWidget global object exposes the following methods for pending reviews:

reviews.open()

Manually open the pending reviews slider. This bypasses the 24-hour delay check, making it suitable for “Write a Review” buttons or menu items.

reviews.close()

Programmatically close the reviews slider.