# JavaScript API

> Open and close the chat from your own buttons, react when it opens, and control Giov Copilot sessions from your page.

Once the widget has loaded, it exposes `window.ChatWidget` on your page. The loader fetches the widget asynchronously, so `ChatWidget` doesn't exist the moment your page starts. Guard your calls:

```js title="app.js"
window.ChatWidget?.open();
```

A command sent while the chat is still starting is applied once it's ready, as long as that happens within 5 seconds.

## Open, close and toggle

```js title="app.js"
ChatWidget.open();                       // open the chat
ChatWidget.open({ view: "fullscreen" }); // open Copilot in a given view
ChatWidget.toggle();                     // open if closed, close if open
ChatWidget.close();
```

| Method | Description |
|---|---|
| `open(options?)` | Opens the chat. |
| `toggle(options?)` | Opens the chat if it's closed, closes it if it's open. |
| `close()` | Closes the chat. |

`options.view` is `"compact"`, `"docked"` or `"fullscreen"` and defaults to `"docked"`. Views apply to the [Giov Copilot](/docs/copilot) panel: the floating widget, a full-height side panel, or the whole page. The regular support chat always opens in its usual window and ignores `view`. Any other value throws an error.

## Open the chat without JavaScript

Add `data-giov-copilot` to any element. A click toggles the chat. Despite the name, it works for the regular support chat as well as for Copilot.

```html title="index.html"
<button type="button" data-giov-copilot>Chat with us</button>
<button type="button" data-giov-copilot="fullscreen">Ask AI</button>
```

- The value picks the view: `compact`, `docked` (the default) or `fullscreen`.
- Only a primary-button click counts. The click's default action is prevented, so a link with this attribute opens the chat instead of navigating.
- Giov keeps `aria-expanded` on every trigger in sync with whether the chat is open.
- Triggers work once the widget has loaded.

## Events

The widget dispatches these events on `window`:

| Event | `event.detail` | When |
|---|---|---|
| `giov:openchange` | `{ open: boolean }` | The chat opens or closes. It also fires once with `open: false` when the chat first renders. |
| `giov:modechange` | `{ mode: "support" \| "checking" \| "copilot" }` | The widget switches between the support chat and Copilot. Fires only when Copilot is active on your site. |

```js title="app.js"
window.addEventListener("giov:openchange", (event) => {
  document.body.classList.toggle("chat-open", event.detail.open);
});
```

> [!NOTE]
> There are no message or conversation events. To act on conversations, use the Inbox, [GiovBot](/docs/giovbot) tools, or the options in [Integrations and API](/docs/api).

## Sessions

These methods manage the signed-in user's sessions: the support chat's and, with [Giov Copilot](/docs/copilot), Copilot's. To identify a support visitor when the page loads, use `window.GiovChatSettings` (see [Identify visitors](/docs/widget/identify-visitors)).

| Method | Description |
|---|---|
| `getMode()` | Returns `"support"`, `"checking"` (verifying the signed-in user) or `"copilot"`. Without Copilot, always `"support"`. |
| `identify({ userId, userHash })` | Tells the widget that a user signed in after the page loaded, for single-page apps. Another user, or `null` when the user signs out, starts a new support conversation and ends the Copilot session. Throws unless you pass `{ userId, userHash }` or `null`. |
| `refreshSession()` | Checks the signed-in user again now. |
| `resetSession()` | Forgets the support conversation in this browser, ends the Copilot session and returns the widget to support mode. Call it on sign-out. |

## Copilot only

These methods only work with [Giov Copilot](/docs/copilot), which is part of the Advanced plan. The Copilot docs explain when and how to use them.

| Method | Description |
|---|---|
| `setContext(context)` | Shares the current page's context with a verified Copilot session. |
| `registerCommand(id, handler)` | Registers a command Copilot can run in your page. Returns a function that removes it. |
| `setAuthHeaders(provider)` | Gives Copilot the headers for actions that run in the browser and authenticate with a token instead of cookies. Pass a function that returns the headers, or `null` to remove it. Headers are kept in memory only. |
| `setLayoutTarget(element)` | Chooses the wrapper element Copilot's docked panel makes room in, instead of the one Copilot detects. Pass your dashboard wrapper, not `body`, `html` or the widget itself, or `null` when it unmounts. |