Control the chat window with JavaScript

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.

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.

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.

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.

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

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.

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:

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.

• 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 . An ID supplied by the browser alone does not prove identity.