Skip to main content
Looking for events your agent triggers during a call (focus an input, open a modal, scroll somewhere)? See Agent Actions. This page covers events the widget itself emits about its own state.
The Ringg AI widget dispatches browser CustomEvent events on window as its state changes. Use these to sync your page UI, track analytics, or run post-conversation workflows. Lifecycle events are supported from v1.0.17+.

​
Event reference

EventFires whenevent.detail
ringg:widget_statusThe widget opens or closes.status: "maximised" or "minimised"; mode: "audio" or "text".
ringg:conversation_statusA voice or chat conversation starts or ends.status: "started" or "ended"; mode: "audio" or "text"; callId: string.
ringg:feedback_statusThe user submits or skips feedback.status: "submitted" or "skipped"; callId: string; optional rating: number.

​
Basic listeners

window.addEventListener("ringg:widget_status", (event) => {
  console.log(event.detail);
  // { status: "maximised", mode: "audio" }
});

window.addEventListener("ringg:conversation_status", (event) => {
  console.log(event.detail);
  // { status: "started", mode: "audio", callId: "abc123" }
});

window.addEventListener("ringg:feedback_status", (event) => {
  console.log(event.detail);
  // { status: "submitted", callId: "abc123", rating: 5 }
});

​
Analytics example

window.addEventListener("ringg:conversation_status", (event) => {
  const { status, mode, callId } = event.detail;

  if (status === "started") {
    analytics.track("Ringg Conversation Started", {
      callId,
      mode,
    });
  }

  if (status === "ended") {
    analytics.track("Ringg Conversation Ended", {
      callId,
      mode,
    });
  }
});

​
Page UI example

Use ringg:widget_status when your page needs to react to the widget state, such as hiding a competing chat launcher. 
const supportLauncher = document.querySelector("[data-support-launcher]");

window.addEventListener("ringg:widget_status", (event) => {
  const { status } = event.detail;

  if (!supportLauncher) {
    return;
  }

  supportLauncher.hidden = status === "maximised";
});

​
React cleanup example

If you attach listeners in a single-page app, remove them when the component unmounts so navigation does not create duplicate handlers. 
import { useEffect } from "react";

export function RinggEventBridge() {
  useEffect(() => {
    function handleConversationStatus(event) {
      const { status, mode, callId } = event.detail;
      console.log({ status, mode, callId });
    }

    window.addEventListener("ringg:conversation_status", handleConversationStatus);

    return () => {
      window.removeEventListener("ringg:conversation_status", handleConversationStatus);
    };
  }, []);

  return null;
}

​
QA notes

Open and close the widget once, then confirm one ringg:widget_status event per action.
Start and end one voice call, then confirm ringg:conversation_status includes a callId.
Submit and skip feedback in separate tests if feedback is enabled.
In single-page apps, navigate away and back, then confirm listeners are not duplicated.