JavaScript API

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

On this page

Open, close and toggle
Open the chat without JavaScript
Events
Sessions
Copilot only

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:

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

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 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.

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.

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 tools, or the options in Integrations and API.

Sessions

These methods manage the signed-in user's sessions: the support chat's and, with Giov Copilot, Copilot's. To identify a support visitor when the page loads, use window.GiovChatSettings (see 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, 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.