Skip to main content

Configuration

The widget is configured through an options object passed to the constructor, or through a JSON data-config attribute on the mount element. When both are present, data-config values win.

let widget = new window.Sitata.claims(el, {
orgId: "<YOUR ORG ID>",
token: "<YOUR PUBLIC TOKEN>",
isB2B: true
});
widget.run();

Options

PropertyTypeDefaultDescription
orgIdStringโ€”Required. Your organization's identifier. The widget will not load without it.
tokenStringโ€”Required. Your organization's public authentication token. Sent as Authorization: PUB <token>.
apiBaseStringhttps://www.sitata.com/api/v2Override the REST API base URL.
isB2BBooleanfalseWhitelabel mode. When true, your branding is used and a "Powered by Sitata" footer is shown. When false, Sitata branding is used.
companyNameString"Sitata"Company name shown in the header and on the login screen.
logoUrlStringโ€”URL of your logo, shown in the header and login screen (whitelabel mode).
primaryColorString#1E88E5Primary theme color (hex).
accentColorString#FF8F00Accent/secondary theme color (hex).
hideHeaderBooleanfalseHide the widget's header bar so it nests inside your own page chrome. A simple inline "Back" control is used instead.
langStringautoForce the UI language (two-letter code, e.g. es). Otherwise a ?lang= URL parameter, then the browser language, then English is used.
widgetTokenStringโ€”A short-lived token you mint server-side for the signed-in customer (see Pre-Authenticating A Customer). When valid, the widget skips the PIN login. Takes precedence over userToken.
onSessionExpiredFunctionโ€”Constructor option only (functions can't go in data-config). Called when the customer's widget session expires; return a freshly minted widgetToken (or a Promise of one) to continue without a reload. See Session Expiry.
userTokenStringโ€”Deprecated โ€” use widgetToken. The customer's permanent authentication token. Still supported, but it never expires, so anyone who reads it from your page can use it indefinitely. The widget logs a console warning when it is used.
subscriptionIdStringโ€”Deep-link: on load, start a new claim under this subscription (policy), skipping the list and policy-selection step.
claimIdStringโ€”Deep-link: on load, open this specific existing claim's detail view.
socketUrlStringwss://sockets.sitata.com/socket/websocketWebSocket endpoint used for live support chat.
httpBaseStringhttps://www.sitata.comBase host used by supporting API helpers.
info

There is no separate currency option โ€” a claim's currency is taken from the policy (subscription) it belongs to.

Example

<div id="claims-app"></div>
<script>
window.document.addEventListener("sitata:claimsReady", function () {
var el = document.getElementById("claims-app");
var widget = new window.Sitata.claims(el, {
orgId: "0774f78c-56ff-47d8-989e-b050d72a2c7f",
token: "f7ed4b59-2981-499b-b33a-b09255cb950f",
isB2B: true,
companyName: "Air Advisor",
logoUrl: "https://airadvisor.com/logo.png",
primaryColor: "#f05800",
accentColor: "#f000e8",
hideHeader: true,
// minted on your server for this page render โ€” see below
widgetToken: "<%= widget_token %>",
subscriptionId: "THE_SUBSCRIPTION_ID"
});
widget.run();
});
</script>
<script async src="https://www.sitata.com/widgets/claims.js"></script>

Pre-Authenticating A Customer

When the customer is already signed in to your portal, you can sign them in to the widget too, so they never see the PIN screen. Do this with a short-lived widget token minted by your server:

  1. Mint on your server. Call POST /api/v2/users/{user_id}/widget_token with your organization's private token. Never do this from the browser โ€” your private token must stay on your server.
  2. Render it into the page as the widgetToken option (constructor or data-config).
  3. The widget exchanges it for a session and signs the customer in. Only that session is stored in the browser.
// Your server (Node.js shown) โ€” runs on every page render
const res = await fetch(`https://www.sitata.com/api/v2/users/${customer.sitataUserId}/widget_token`, {
method: "POST",
headers: {
Authorization: `TKN ${process.env.SITATA_PRIVATE_TOKEN}`,
"Content-Type": "application/json",
},
});
const { widget_token } = await res.json();
// pass widget_token to your page template as `widgetToken`
LifetimeNotes
Widget token5 minutesSingle use. Mint a new one every time you render the widget โ€” a reloaded page that reuses an old token falls back to the PIN screen.
Widget session12 hoursCreated by the widget from the token. Expires on its own; it is never your customer's permanent credential.

You can mint for a customer who is a traveller at your organization (for example, they bought a policy through you) and has no other role. Optionally pass subscription_id to bind the token to one of their policies.

If the token can't be used (expired, already used, or not valid), the widget clears any stored session and shows the PIN login, so the customer can still sign in.

Session Expiry

When a widget session expires โ€” or the API rejects it โ€” the widget signs the customer out of the widget, shows the PIN login, and then:

  • fires sitata:claimsSessionExpired on document, with the widget instance at event.detail.widget, and
  • calls your onSessionExpired(widget) callback, if you provided one.

To keep the customer signed in, fetch a fresh token from your server and either return it from onSessionExpired or pass it to widget.setWidgetToken(token):

var widget = new window.Sitata.claims(el, {
orgId: "<YOUR ORG ID>",
token: "<YOUR PUBLIC TOKEN>",
widgetToken: "<TOKEN MINTED FOR THIS RENDER>",
onSessionExpired: async function () {
// your own endpoint, which mints a widget token server-side
var res = await fetch("/my-portal/sitata-widget-token", { credentials: "include" });
if (!res.ok) return null; // customer is no longer signed in to your portal: show PIN login
return (await res.json()).widgetToken;
}
});
widget.run();

If you configure the widget through data-config, listen for the event instead:

document.addEventListener("sitata:claimsSessionExpired", async function (event) {
var token = await getFreshWidgetTokenFromMyServer();
if (token) event.detail.widget.setWidgetToken(token);
});

Signing Out

When the customer signs out of your portal, sign them out of the widget as well โ€” otherwise the widget session stays in the browser until it expires, which matters on shared devices:

await widget.logout();

logout() revokes the widget session on Sitata's side, clears everything the widget stored in the browser, and returns the widget to the login screen.

Migrating From userToken

userToken keeps working, but it places your customer's permanent API token in your page. Switch to widgetToken:

  1. Add the server-side mint call above.
  2. Replace userToken: "..." with widgetToken: "<minted token>".
  3. Add widget.logout() to your sign-out flow and, optionally, onSessionExpired.

Methods

MethodDescription
run()Authenticates your organization and the customer, then mounts the widget. Returns a Promise of the widget.
setWidgetToken(token)Signs a customer in with a freshly minted widget token, without reloading. Resolves true on success; on failure the widget shows the PIN login and resolves false.
logout()Signs the customer out of the widget: revokes the widget session, clears stored credentials and live chat, and shows the login screen.

Deep-Linking A Customer To A Claim

The widget scopes claims to a customer's subscriptions (policies). To send a specific customer straight to the right place, combine:

  1. orgId + token โ€” identify your organization.
  2. widgetToken โ€” pre-authenticate the customer so they skip login (see Pre-Authenticating A Customer).
  3. Either subscriptionId (start a claim under that policy) or claimId (open an existing claim).

As a fallback, if the page's own URL path ends with a claim's UUID, the widget will detect it and open that claim. An explicit claimId takes precedence over the URL.

Events

The widget exposes these lifecycle events:

EventDescription
sitata:claimsReadyFired on document once the widget bundle has loaded and is ready to be instantiated. Initialize the widget inside a listener for this event.
sitata:claimsSessionExpiredFired on document when the customer's widget session expires or is rejected. event.detail.widget is the widget instance; call setWidgetToken() on it to sign the customer back in. See Session Expiry.
warning

Apart from these, the widget does not emit domain callbacks such as "claim submitted" or "status changed" to the host page โ€” its state stays inside the widget. If you need your portal to react to claim progress, drive it from the server-side claim webhooks (events 600โ€“607) instead.

Styling

Theming is driven by the primaryColor and accentColor options. The widget renders as a responsive, full-width application and inherits your page's font, so in most cases setting your brand colors, logoUrl, and hideHeader is all that is needed. The widget currently renders in a light theme.

Environments

The loader and widget bundle are served from Sitata's own domain:

EnvironmentLoader script
Productionhttps://www.sitata.com/widgets/claims.js
Staginghttps://staging.sitata.com/widgets/claims.staging.js

Point apiBase (and, if used, socketUrl) at the matching environment.