Widget Integration

The widget is a standalone bundle served from Supportly and mounted inside a Shadow DOM. That keeps host-site CSS from leaking into the chat UI while still allowing simple script-based installation.

Embed options by framework

The simplest installation is a script tag in plain HTML, but the widget can also be loaded from framework lifecycle hooks when you need environment-aware key selection or conditional loading.

Embed snippets

Choose the pattern that matches your host application. All variants eventually load the same widget bundle.

index.htmlhtml

1<script
2  src="https://your-supportly-domain.com/widget.js?v=YOUR_WIDGET_VERSION"
3  data-workspace-key="ws_live_xxxxxxxxx"
4></script>

Configuration options

Setting	Purpose	Recommended default
Primary color	Controls brand emphasis in the launcher and chat UI	Use the brand accent already used for calls to action.
Welcome message	Sets the first interaction expectation	Keep it under two sentences and action oriented.
Pre-chat fields	Captures routing data before the first message	Only enable name and email if agents truly need them.
Auto-open delay	Opens the widget after a delay	Use sparingly on pricing or checkout help pages only.

Avoid over-configuring pre-chat

Every extra field lowers start rate. If the agent can gather context naturally in the first turn, prefer that over a long pre-chat form.

Passing customer context

When you create widget sessions through the public API, include only the context that improves resolution speed: customer identity, page URL, browser data, or known account metadata.

Supportly stores this context on the conversation so it can inform AI responses, operator handoff, and later ticket review.

Create a widget session

This request creates or resumes a conversation and returns the token used for widget transport.

create-session.shbash

1curl -X POST "https://your-supportly-domain.com/api/widget/session"   -H "Content-Type: application/json"   -H "x-api-key: ws_live_xxxxxxxxx"   -d '{
2    "customerName": "Amina Khalid",
3    "customerEmail": "amina@example.com",
4    "metadata": {
5      "pageUrl": "https://example.com/pricing",
6      "browser": "Chrome",
7      "plan": "pro-trial"
8    }
9  }'