> ## 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)