Widget Controls

This guide covers how to open and close the widget programmatically.

<!-- 1️⃣  Drop the script anywhere inside <body>  -->
<script src="https://console.olivya.io/chat/widget/<agent_id>" defer></script>

All sizing, colours and alignment come from the dashboard settings for the agent.

The script injects:

a floating round button (bottom‑left or bottom‑right, depending on your settings)
a modal that hosts the full chat UI inside an <iframe>

2 · Meet `window.olivyaWidget`Copied!

Once the script has finished running it exposes a global helper on window:

interface olivyaWidget {
  /** open the chat (no‑op if already open) */
  open(): void;

  /** close the chat (no‑op if already closed) */
  close(): void;

  /** open if closed • close if open */
  toggle(): void;

  /**
   * send any serialisable value to the iframe –
   * you can listen for it with `window.addEventListener("message", …)` inside your bot UI
   */
  postMessage(data: any): void;
}

// available globally after the script loads
declare const olivyaWidget: OlivyaWidget;

Typical uses

// open the chat when the page has been idle for 30 s
setTimeout(() => olivyaWidget.open(), 30000);

// tie it to your own button
myBtn.addEventListener("click", () => olivyaWidget.toggle());

// close the chat after a successful order
placeOrder().then(() => olivyaWidget.close());

3 · Load‑order safetyCopied!

olivyaWidget appears after widget.js executes.
If you call it too early youʼll hit TypeError: olivyaWidget is undefined.

Recommended patterns

Put your code underneath the <script> tag:

<script src="https://console.olivya.io/chat/widget/<agent_id>" defer></script>
<script>
  olivyaWidget.open();
</script>

or wait for DOMContentLoaded:

window.addEventListener("DOMContentLoaded", () => olivyaWidget.open());

or use the scriptʼs onload event (good for React / Vue DSLs):

const s = document.createElement("script");
s.src = "https://cdn.mychat.com/widget.js";
s.dataset.chatbotId = "123";
s.onload = () => olivyaWidget.toggle();
document.body.appendChild(s);

4 · Controlling the widget via `postMessage`Copied!

Any frame on the page can ask the widget to open/close by posting a small message:

window.postMessage({ action: "openChatbot" }, "*");
window.postMessage({ action: "closeChatbot" }, "*");
window.postMessage({ action: "toggleChatbot" }, "*");

Inside your own code you can listen to whatever is sent from the chatbot iframe too:

window.addEventListener("message", (event) => {
  console.log("message from bot UI", event.data);
});

5 · Troubleshooting cheatsheetCopied!

Symptom	Likely cause	Fix
`olivyaWidget is undefined`	Called before widget.js finished loading	Use any of the load‑order patterns above
Button shows but modal never opens	An element on the page is swallowing `z-index`	Inspect in DevTools; raise the widgetʼs `z-index` if needed
I need to style the modal	Use the Appearance tab in the dashboard; CSS is injected inline at runtime