Widget JS API - Tars Docs

This reference covers window.TarsWidget, the host-page control object created by embed.js. It exists only with the script embed method, not with a direct iframe.

Availability

embed.js defines window.TarsWidget only after it loads the agent’s widget settings, so the object can be missing when your own script runs. Guard early calls.

if (window.TarsWidget) {
  window.TarsWidget.open();
}

Methods

Method	Returns	Description
`open()`	void	Opens the widget panel. Builds the iframe if the preload has not already done so. Recorded as an API-triggered open in visit analytics
`close()`	void	Closes the panel and notifies the widget
`isOpen()`	boolean	`true` while the panel is open
`showBadge(count)`	void	Shows an unread badge on the launcher with `count`. Values over 99 display as “99+“
`hideBadge()`	void	Hides the unread badge
`identify(identitySignature)`	void	Attaches a signed identity `{ kid, payload, sig }` mid-session

Badge behavior

The badge renders only while the widget is closed. Opening the panel clears it. The widget also sets the badge itself from unread live-chat messages, so call showBadge only for your own counts.

identify

identify verifies an end user who signs in after the conversation already started. The widget forwards the signature to Tars, which verifies it server-side. The payload’s sub claim must equal the widget’s channelUserId, see Identity signing for the full contract.

window.TarsWidget.identify({
  kid: "YOUR_KEY_ID",
  payload: "BASE64_PAYLOAD",
  sig: "BASE64_SIGNATURE"
});