Listen for web widget events

Each is a CustomEvent on window. Use them to send analytics, hide a competing chat launcher, or start a follow-up after the conversation. Events the agent fires on purpose during a conversation (focus a field, open a modal) are a different feature: see Agent actions.

Before you start

An installed widget

The events fire from CDN version 1.0.17 onward.

Event reference

Event	Fires when	`event.detail`
`ringg:widget_status`	The panel opens or closes.	`status`: `"maximised"` or `"minimised"`. `mode`: `"audio"` or `"text"`.
`ringg:conversation_status`	A call or chat starts or ends.	`status`: `"started"` or `"ended"`. `mode`. `callId`.
`ringg:feedback_status`	The visitor submits or skips the rating.	`status`: `"submitted"` or `"skipped"`. `callId`. `rating` (submitted only).
`ringg:calendar_booking`	A legacy calendar or form is shown or completed. On `2.0.0-beta` builds it also fires for every component shown and every button tap on one, not only calendars.	`status`: `"shown"` or `"confirmed"`. `componentId`. `message` (confirmed only).

Send events to analytics

window.addEventListener("ringg:conversation_status", (event) => {
  const { status, mode, callId } = event.detail;
  analytics.track(status === "started" ? "Ringg conversation started" : "Ringg conversation ended", { mode, callId });
});

window.addEventListener("ringg:feedback_status", (event) => {
  const { status, rating, callId } = event.detail;
  if (status === "submitted") analytics.track("Ringg rating", { rating, callId });
});

React to the panel

Hide your own support launcher while the widget is open:

const supportLauncher = document.querySelector("[data-support-launcher]");

window.addEventListener("ringg:widget_status", (event) => {
  if (supportLauncher) supportLauncher.hidden = event.detail.status === "maximised";
});

Clean up in single-page apps

Add listeners once and remove them on unmount; otherwise every client-side navigation adds another handler.

import { useEffect } from "react";

export function RinggEventBridge() {
  useEffect(() => {
    function onConversation(event) {
      console.log(event.detail);
    }
    window.addEventListener("ringg:conversation_status", onConversation);
    return () => window.removeEventListener("ringg:conversation_status", onConversation);
  }, []);

  return null;
}

Verify your listeners

Opening and closing the panel fires one ringg:widget_status each.
A test call fires ringg:conversation_status twice, both with the same callId.
Submitting and skipping the rating (in separate runs) each fire ringg:feedback_status.
After navigating away and back in your app, each event still fires once.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Web widget events

Before you start

An installed widget

Event reference

Send events to analytics

React to the panel

Clean up in single-page apps

Verify your listeners

Next steps

Drive your page from the agent

Prepare for launch

​Before you start

An installed widget

​Event reference

​Send events to analytics

​React to the panel

​Clean up in single-page apps

​Verify your listeners

​Next steps

Drive your page from the agent

Prepare for launch

Before you start

Event reference

Send events to analytics

React to the panel

Clean up in single-page apps

Verify your listeners

Next steps