Control the chat window with JavaScript

Open the chat window from your own button, listen for events and pass analytics consent from your website.

Open copy menu

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 to call an agent from your server, webhooks to receive events and identity verification to pass signed user information.

Before you start

Install the embed code provided by Oma Aihio using the publishing guide . 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.

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

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.

Listen for opening

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.

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

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

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

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.

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:

The new chat window (Widget Runtime v2)
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 . An ID supplied by the browser alone does not prove identity.