> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget JS API

> The window.TarsWidget methods for opening, closing, badging, and identifying from the host page.

This reference covers `window.TarsWidget`, the host-page control object created by `embed.js`. It exists only with the [script embed method](/docs/developer/embed/script-and-config), 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.

```js theme={null}
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](/docs/developer/embed/identity-signing) for the full contract.

```js theme={null}
window.TarsWidget.identify({
  kid: "YOUR_KEY_ID",
  payload: "BASE64_PAYLOAD",
  sig: "BASE64_SIGNATURE"
});
```

## Related pages

* [Embed script and TarsConfig](/docs/developer/embed/script-and-config)
* [Host page events](/docs/developer/embed/host-page-events)
* [Identity signing](/docs/developer/embed/identity-signing)