# Control the chat window with JavaScript

URL: https://aihio.ai/en/help/ai-agent/widget-api\
Description: Open the chat window from your own button, listen for events and pass analytics consent from your website.

Use the JavaScript API to connect the Aihio chat window to your website's controls. This guide covers opening the window, listening for its opening event and connecting analytics to your site's consent choice.

Choose an integration by task: this guide covers the website chat window. Use the [message API](/en/help/ai-agent/message-api) to call an agent from your server, [webhooks](/en/help/ai-agent/webhooks) to receive events and [identity verification](/en/help/ai-agent/identity-verification) to pass signed user information.

## Before you start

Install the embed code provided by Oma Aihio using the [publishing guide](/en/help/ai-agent/publish). Place your calls after that snippet. Its command queue accepts calls before the chat window finishes loading.

This guide applies to the JavaScript embed. These host-page calls do not control the window inside a separate iframe embed. Do not install the same embed twice.

## Open the window from your button

Add a button with the ID `open-chat` to your website, then add this JavaScript to your own site code. It assumes that the button and Aihio embed snippet are already present.

```javascript
document.getElementById('open-chat')?.addEventListener('click', () => {
  window.AihioWidget('open');
});
```

Press the button: the chat window should open without navigating to another page. Close it with its own close button. Remove your event handler to return to using only the Aihio launcher.

## Choose the right command

| Command       | Effect                                                             |
| ------------- | ------------------------------------------------------------------ |
| `open`        | Opens the chat window.                                             |
| `close`       | Closes the chat window.                                            |
| `show`        | Shows the launcher.                                                |
| `hide`        | Hides the launcher.                                                |
| `toggle`      | Toggles launcher visibility, not whether the chat window is open.  |
| `sendMessage` | Sends the supplied text as a user message.                         |
| `identify`    | Passes user identity details or a server-signed JWT.               |
| `resetUser`   | Clears the identity set in the chat window, for example on logout. |
| `consent`     | Updates analytics consent.                                         |
| `on`          | Registers an event handler.                                        |

`init` belongs to the embed snippet generated by Oma Aihio. Do not initialize the window again just to open it. `update` exists for runtime settings, but make ordinary appearance changes in Oma Aihio.

> **Warning — Sending a message is a real action:**
>
> `sendMessage` sends a message to the agent and uses the service like an
> ordinary conversation. Call it only after an intentional user action.
> `resetUser` does not delete conversations stored by the service.

## Listen for opening

```javascript
window.AihioWidget('on', 'open', () => {
  console.info('Chat window opened');
});
```

Open the window and check the browser console for the message. Register the handler once so that route changes on your website do not register it repeatedly.

Supported events are `ready`, `open`, `close`, `message` and `error`. `message` includes the message role, content and ID. Do not send conversation content to analytics or console logs. Ordinary opening observation needs only `open`, without message data.

## Connect analytics consent

Pass the actual choice from your site's consent manager. Call this only after the user has accepted analytics:

```javascript
window.AihioWidget('consent', { analytics: true });
```

When the user declines analytics or withdraws earlier consent, pass the refusal:

```javascript
window.AihioWidget('consent', { analytics: false });
```

Missing consent does not allow behavioral analytics. The browser's Do Not Track setting prevents it even after consent. This call does not replace your consent manager or cover every request needed to deliver a conversation.

Test acceptance and withdrawal separately in the browser network panel. Behavioral observation events must not be sent when analytics is declined; requests needed for the conversation can still work. An opening chat window alone does not prove correct consent handling.

## The new chat window (Widget Runtime v2)

When the embed code from Oma Aihio loads a script ending in `/widget/v2/loader.js`, your page runs the new chat window. The call style is the same `window.AihioWidget(...)`, but the command set is smaller and deliberately stricter:

| Command                    | Effect                                                                                                                                                                                                                            |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`, `close`            | Opens or closes the chat window.                                                                                                                                                                                                  |
| `show`, `hide`             | Shows or hides the launcher.                                                                                                                                                                                                      |
| `on`, `off`                | Registers or removes an event handler.                                                                                                                                                                                            |
| `requestConversationReset` | Call `AihioWidget('requestConversationReset', { version: 1 })`. Asks the visitor to confirm ending the conversation; never ends it by itself. Works only once conversation ending is enabled; otherwise the window emits `error`. |
| `destroy`                  | Removes the window and launcher from the page.                                                                                                                                                                                    |

Events are `ready`, `open`, `close`, `message` and `error`. In the new window `message` only reports that the agent replied: it carries no text, role or ID, so conversation content stays inside the window.

`toggle`, `sendMessage`, `identify`, `resetUser`, `consent` and `update` are not available in the new window. Signed-in user identification and the pre-chat form arrive in the new window as their own features; until then, agents that require identification or a mandatory pre-chat form keep using the current window. Sending a message on the user's behalf is left out on purpose.

## If a call does not work

- **`AihioWidget` is missing:** check that the embed loads and that your code runs after the snippet.
- **The button does not respond:** check the HTML element ID and register the handler only after the element exists.
- **`toggle` does not close the window:** use `close` to close it.
- **`sendMessage` or `identify` does nothing:** your embed loads the new window (`/widget/v2/loader.js`), which has neither command.
- **Consent withdrawal is not passed:** check the exact field name `analytics` and boolean `false`, not the string `'false'`.

Signed-in user information needs separate [identity verification](/en/help/ai-agent/identity-verification). An ID supplied by the browser alone does not prove identity.
## Next steps

- [Identity verification](/en/help/ai-agent/identity-verification) — Pass server-signed user information and choose the right verification method for your chat window.