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
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.
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
TheSalesiveWidget 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. Returnstrue 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.chat.on(event, handler)
Listen for real-time socket events from the chat system.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.Route filtering
Control which pages display the widget using theroutes 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
Usechat.hide(), chat.show(), and chat.toggleVisibility() to control visibility without losing chat state:
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.Pre-init theming (recommended)
Setwindow.SalesiveWidgetConfig before the widget script loads to apply your brand colors on first render with no flash of default colors:
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 theinit() 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 viaSalesiveWidget.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
TheSalesiveWidget 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
TheSalesiveWidget 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 thebeforeinstallprompt 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
TheSalesiveWidget global object exposes the following methods for pending reviews:

