# 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. `open({ draft: 'text' })` also fills an empty message field with at most 2,000 characters; the visitor decides whether to send it. |
| `close`     | Closes the chat window.                                                                                                                                   |
| `show`      | Shows the launcher.                                                                                                                                       |
| `hide`      | Hides the launcher.                                                                                                                                       |
| `toggle`    | Toggles launcher visibility, not whether the chat window is open.                                                                                         |
| `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.                                                                                                                               |
| `off`       | Removes a handler registered with `on`. Pass the same function you registered.                                                                            |
| `update`    | Changes runtime settings. Make ordinary appearance changes in Oma Aihio.                                                                                  |
| `init`      | Starts the chat window. The embed snippet generated by Oma Aihio already calls it; do not call it to open it.                                             |
| `destroy`   | Removes the chat window and the launcher from the page, for example when consent is withdrawn. Repeats do nothing. A later `init` starts them again.      |

> **Note — The visitor sends the message:**
>
> No command sends a message on the visitor's behalf. `open({draft})` fills the
> message field only when it is empty, and the visitor decides whether to send
> it. `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.

| Event     | Fires when                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| `ready`   | The chat window has loaded its settings. With the standard embed, this usually happens when the window first opens. |
| `open`    | The chat window opens, from your code or from the launcher.                                                         |
| `close`   | The chat window closes.                                                                                             |
| `message` | A message is added to the conversation. Includes the message ID and role, never its text.                           |
| `error`   | The chat window could not load its settings.                                                                        |

No event carries the text of a conversation. Ordinary opening observation needs only `open`.

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

## Identify a signed-in visitor

Identity values travel in request headers, so they must use Latin-1 characters. A `name` or `email` with other characters, such as "Šárka", is left out and the rest of the identity is kept. An `externalId`, `user_hash` or `token` with other characters leaves the whole identity out, as if `identify` had not been called.

When your site knows who the visitor is, pass the identity to the window:

```javascript
window.AihioWidget('identify', {
  externalId: 'customer-12345',
  name: 'Maija Meikäläinen',
  email: 'maija@example.com',
  user_hash: 'HMAC proof computed on your server',
});
```

The fields are `externalId` (or the Chatbase-compatible `user_id`), `email`, `name`, `user_hash`
and `token` (a server-signed JWT). With a `token`, also pass `getToken`, a function that returns a
new JWT for the same user when the old one expires. No other fields are needed. `user_hash` and `token` are the
proof, verified on the server with the agent's own secret; without a proof the identity is only a
hint and does not bind the conversation to the visitor. Call `resetUser` on sign-out.

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