Customize the Ringg AI Web Widget

Every notable element rendered by the widget carries a stable data-ringg="<name>" attribute, and state-bearing elements carry additional data-ringg-<state> attributes that update as the widget changes state. Use them as CSS selectors or JS query targets to restyle, hide, rearrange, or script the widget.

Do not target the internal ringg_ai-* class names. They are minified output and change between releases. Style and script the widget through data-ringg attributes only.

Quick example

[data-ringg="trigger-button"] {
  background: #4F46E5;
  border-radius: 50%;
}

[data-ringg="message"][data-ringg-role="agent"] [data-ringg="message-bubble"] {
  font-style: italic;
}

document.querySelector('[data-ringg="mute-button"]')?.click();

State attributes

State-bearing elements expose additional data-ringg-<state> attributes. They update live, so you can drive CSS off them with attribute selectors or watch them with MutationObserver.

Attribute	Values	Emitted on
`data-ringg-role`	`"agent"` / `"user"`	`message`
`data-ringg-muted`	`"true"` / `"false"`	`mute-button`
`data-ringg-connecting`	`"true"` / `"false"`	`header-status-dot`
`data-ringg-align`	`"center"` / `"end"`	`quick-replies` (centered in voice, right-aligned in chat)
`data-ringg-style`	`"primary"` / `"secondary"` / `"outline"` / `"destructive"`	`quick-reply-button`, `option-row`
`data-ringg-variant`	`"transcript"`	`feedback-screen` (present when the ended transcript stays readable)
`data-ringg-active`	`"true"` / `"false"`	`slash-command-item`
`data-ringg-lit`	`"true"` / `"false"`	`voice-animation-dot`
`data-ringg-level`	`"info"` / `"error"`	`system-log`
`data-ringg-step-active`	`"true"` / `"false"`	`flow-step`
`data-ringg-step-completed`	`"true"` / `"false"`	`flow-step`
`data-block-id`	authored id string	any Block Kit node with an author id
`data-action-id`	action id string	`block-button`

Compound selector example:

[data-ringg="mute-button"][data-ringg-muted="true"] {
  background: var(--brand-danger);
}

Observer example:

const muteButton = document.querySelector('[data-ringg="mute-button"]');

new MutationObserver(() => {
  console.log("muted?", muteButton.getAttribute("data-ringg-muted"));
}).observe(muteButton, {
  attributes: true,
  attributeFilter: ["data-ringg-muted"],
});

Element reference

Elements are grouped by where they appear in the widget.

Top level

`data-ringg`	Element
`trigger-button`	Floating launcher button. Visible when the widget is closed.
`trigger-icon`	The `<img>` rendered inside the trigger button.
`widget-root`	Outer widget container that wraps every other widget element. Top of the panel tree.
`widget-body`	Inner flex column inside the widget. Wraps the panel and footer.
`widget-panel`	Padded main panel. Header, body, and controls render here.
`minimize-button`	Top-right minimize icon. Only present during a call.
`close-button`	Top-right close icon. Aria label flips to `"End call"` during a call.
`voice-animation-wrapper`	Container around the voice visualizer. Audio mode only.
`body-spacer`	Empty placeholder that keeps controls anchored when the body is empty.
`transcript`	Scrollable message area.
`transcript-list`	Inner flex list of messages.
`controls-bar`	Transparent bar anchoring the message input over the transcript (chat mode). The transcript scrolls underneath it.
`attached-buttons`	Full-width wrapper for quick replies rendered directly below an agent message.
`connecting-status`	Wrapper for the pre-call connecting state (“Connecting…” label + loading bar).
`connecting-label`	The `"Connecting…"` `<p>` above the loading bar.
`error-message`	Inline error text.
`legal-disclaimer`	Pre-call legal `<p>`.
`legal-link-privacy`	Privacy policy link inside the legal disclaimer.
`legal-link-terms`	T&C link inside the legal disclaimer.

`data-ringg`	Element
`header`	In-call header band. Only present during a call, which integrators use to detect an active call (e.g. `:has([data-ringg="header"])`). Absolute-positioned frosted overlay.
`intro`	Pre-call container. Centered logo/title/description block on the start screen (the pre-call counterpart to `header`).
`header-logo`	Logo chip. Both pre-call (rounded square) and in-call.
`header-logo-image`	The `<img>` inside the logo chip.
`header-text`	Text wrapper that holds the title and description.
`header-title`	Title `<h2>`.
`header-description`	Description `<p>`. Shown pre-call and in-call. Truncated in-call (full text on hover via `title`).
`header-status-dot`	Presence dot. In-call only. Carries `data-ringg-connecting`: muted and pulsing while connecting, success-colored once live.
`header-status`	Screen-reader-only status `<p>`. In-call only; visible status is the dot. The pre-call connecting status moved to `connecting-label`.

Call controls (audio mode)

Compact centered mute/end pair, no text labels, since icons carry the meaning.

`data-ringg`	Element
`call-controls`	Row container holding the call control buttons.
`mute-button`	Mute toggle button (aria-label `"Mute"` / `"Unmute"`). Carries `data-ringg-muted`.
`end-call-button`	End-call button (aria-label `"End call"`).

Action buttons (start screen)

The start screen shows both buttons side by side (Chat left, Call right), each starting its mode directly. With hideTabSelector: true only the defaultTab mode’s button renders, full-width.

`data-ringg`	Element
`start-actions`	Row wrapping the Chat + Call pair. Only when both buttons are shown.
`start-call-button`	Starts a voice call.
`start-chat-button`	Starts a chat.

Loading bar

`data-ringg`	Element
`loading-bar`	Loading bar container.
`loading-bar-track`	Background track.
`loading-bar-fill`	Animated fill.

Quick replies and options

Quick-reply chips (free presentation) and boxed option lists rendered below an agent message.

`data-ringg`	Element
`quick-replies`	Chip row container. Carries `data-ringg-align` (`"center"` in voice, `"end"` in chat).
`quick-reply-button`	Each pill chip. Carries `data-ringg-style`.
`buttons-step-title`	Optional title `<p>` above the chips.
`options-list`	Boxed single-choice list container (rows divided by hairlines).
`option-row`	Each option row. Carries `data-ringg-style`.
`option-radio`	Radio affordance inside an option row.

Typing indicator

Shown while an agent reply is pending. Cycles through words (default: Thinking / Reasoning / Working on it / Almost there; override with the typingWords config) each rendered with a left→right text shimmer.

`data-ringg`	Element
`typing-indicator`	Outer row.
`typing-indicator-word`	The shimmering current word `<span>`.

Messages

`data-ringg`	Element
`message`	Outer message row. Carries `data-ringg-role="agent"` / `"user"`.
`message-bubble`	The bubble inside a message row. Agent messages are bubble-less unless the theme sets `agentBubbleColor`.
`message-content`	Inner column inside the bubble.
`message-body`	Markdown-rendered message body.
`message-source`	”Source:” link rendered below a message.

System log pill

The system log pill renders the inline activity feed in the transcript. It only shows up when you opt in via loadAgent({ eventLogs: { enabled: true } }). See Agent actions for details.

`data-ringg`	Element
`system-log`	Outer container. Carries `data-ringg-level="info"` / `"error"`.
`system-log-pill`	Pill body.
`system-log-dot`	Status dot.
`system-log-label`	Label text.
`system-log-meta`	Optional meta text.

`data-ringg`	Element
`slash-command-menu`	Outer container.
`slash-command-header`	Header bar with the title.
`slash-command-heading`	”Commands” label.
`slash-command-list`	Scrollable list of command items.
`slash-command-item`	Each command button. Carries `data-ringg-active`.
`slash-command-icon`	Icon square inside an item.
`slash-command-text`	Text column inside an item.
`slash-command-name`	Command display name.
`slash-command-description`	Command description text.

Voice animation

`data-ringg`	Element
`voice-animation`	Visualizer root (set on the same element that receives `localTrack`/`remoteTrack`).
`voice-animation-column`	One column of dots (22 columns per visualizer).
`voice-animation-dot`	Individual dot. Carries `data-ringg-lit`, which flips per audio frame.

data-ringg-lit updates at audio rate. Keep CSS transitions on it lightweight, for example transition: opacity 50ms. Heavy transitions or expensive observers on this attribute will fire every frame.

Interactive flow

`data-ringg`	Element
`interactive-flow`	Outer container.
`flow-stepper`	Stepper header (shown only when multi-step).
`flow-stepper-progress`	Row of step indicators.
`flow-step`	Each step + connector pair. Carries `data-ringg-step-active` and `data-ringg-step-completed`.
`flow-step-indicator`	Numbered/check circle for each step.
`flow-step-connector`	Line between steps.
`flow-step-title`	Current step title `<p>`.
`flow-content`	Step body wrapper.
`flow-back-button`	Back navigation button.
`flow-submitted-selection`	Submitted-state wrapper.
`flow-submitted-pill`	Pill showing the selected choice.

Message input (text mode)

`data-ringg`	Element
`message-input-form`	The `<form>` element.
`message-input`	Outer pill container carrying the frosted-glass treatment; transparent gutters. Also wraps the slash menu when open (going solid).
`message-input-row`	Row containing the input field + send button.
`message-input-field`	The `<input>` element.
`message-send-button`	Send arrow button.

Feedback screen

When the ended conversation has text messages, the transcript stays readable and the rating renders as a footer below it (data-ringg-variant="transcript"); tapping a star submits immediately. The legacy centered card (comment box + submit/skip) renders when there is no transcript. Transcript variant

`data-ringg`	Element
`feedback-screen`	Container. Carries `data-ringg-variant="transcript"`.
`feedback-footer`	Divider + prompt + stars block below the read-only conversation.
`conversation-ended`	”Conversation ended” hairline divider row.
`feedback-prompt`	”Please rate your experience” `<p>`.
`feedback-stars`	Star row.
`feedback-star`	Each star button. Carries `data-ringg-filled`.

Legacy centered card

`data-ringg`	Element
`feedback-screen`	Container.
`feedback-header`	Title + description block.
`feedback-title`	Title `<h3>`.
`feedback-description`	Description `<p>`.
`feedback-stars`	Star row.
`feedback-star`	Each star button.
`feedback-comment`	Comment `<textarea>`.
`feedback-actions`	Submit + skip wrapper.
`feedback-submit`	Submit button.
`feedback-skip`	Skip button.

Components

Block trees the agent streams on the ringg.blocks topic: the cards, forms and pickers built under Embed & Widgets → Components (see Components). Rendered full-width in the transcript.

`data-ringg`	Element
`blocks-widget`	Transcript wrapper around one Block Kit instance.
`blocks`	Root of the rendered tree.
`block-<type>`	Every rendered node, named by its catalog type (e.g. `block-card`, `block-carousel`, `block-table`, `block-steps`, `block-input_rating`). Carries `data-block-id` when the author set one.
`block-button`	Action button. Carries `data-block-id` and `data-action-id`.
`blocks-unsupported`	Fallback `<p>` when the payload needs a newer widget version.

`data-ringg`	Element
`footer`	Footer bar at the bottom of the widget.
`footer-brand`	”Ringg AI” brand text.

End-call confirm dialog

The end-call confirm dialog renders in a portal outside [data-ringg="widget-root"]. Scope its selectors at the document level.

`data-ringg`	Element
`end-call-dialog`	Dialog content root.
`end-call-dialog-header`	Header wrapper inside the dialog.
`end-call-dialog-title`	Dialog title `<h2>`.
`end-call-dialog-description`	Dialog description `<p>`.
`end-call-dialog-footer`	Dialog footer wrapper.
`end-call-cancel`	Cancel button.
`end-call-confirm`	End-call confirm button.

Common recipes

Restyle the launcher

[data-ringg="trigger-button"] {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
  box-shadow: 0 10px 25px rgba(99, 102, 241, 0.4);
}

Style the muted state

[data-ringg="mute-button"][data-ringg-muted="true"] {
  background: var(--brand-danger);
  color: #fff;
}

Glow on lit visualizer dots

[data-ringg="voice-animation-dot"][data-ringg-lit="true"] {
  box-shadow: 0 0 8px currentColor;
}

Italicize agent messages

[data-ringg="message"][data-ringg-role="agent"] [data-ringg="message-bubble"] {
  font-style: italic;
}

[data-ringg="footer"] {
  display: none;
}

function onWidgetReady(cb) {
  const found = document.querySelector('[data-ringg="widget-root"]');
  if (found) return cb(found);

  const observer = new MutationObserver(() => {
    const el = document.querySelector('[data-ringg="widget-root"]');
    if (el) {
      observer.disconnect();
      cb(el);
    }
  });
  observer.observe(document.body, { childList: true, subtree: true });
}

onWidgetReady((root) => {
  analytics.track("Ringg Widget Mounted");
});

Capture feedback submissions

document.addEventListener("click", (event) => {
  if (event.target.closest('[data-ringg="feedback-submit"]')) {
    analytics.track("Ringg Feedback Submitted");
  }
});

For lifecycle hooks like open/close, conversation start/end, and the feedback payload itself, listen to the events documented in Widget Lifecycle Events. Use data-ringg attributes for UI affordances the widget does not surface as events.

QA notes

All your selectors target [data-ringg="..."] attributes, not internal ringg_ai-* class names.

Compound selectors with state attributes (for example [data-ringg="mute-button"][data-ringg-muted="true"]) update live as the widget changes state.

Selectors for the end-call confirm dialog are document-scoped, not nested under [data-ringg="widget-root"].

CSS transitions on [data-ringg-lit] are lightweight, so per-frame state changes do not cause jank.

Get Started

API Reference

Webhooks Setup

Telephony Integration

External Integrations

Privacy and Compliance

Widget Customization

Quick example

State attributes

Element reference

Top level

Header

Call controls (audio mode)

Action buttons (start screen)

Loading bar

Quick replies and options

Typing indicator

Messages

System log pill

Slash command menu

Voice animation

Interactive flow

Message input (text mode)

Feedback screen

Components

Footer

End-call confirm dialog

Common recipes

Restyle the launcher

Style the muted state

Glow on lit visualizer dots

Italicize agent messages

Hide the footer brand

Wait for the widget to mount

Capture feedback submissions

QA notes

​Quick example

​State attributes

​Element reference

​Top level

​Header

​Call controls (audio mode)

​Action buttons (start screen)

​Loading bar

​Quick replies and options

​Typing indicator

​Messages

​System log pill

​Slash command menu

​Voice animation

​Interactive flow

​Message input (text mode)

​Feedback screen

​Components

​Footer

​End-call confirm dialog

​Common recipes

​Restyle the launcher

​Style the muted state

​Glow on lit visualizer dots

​Italicize agent messages

​Hide the footer brand

​Wait for the widget to mount

​Capture feedback submissions

​QA notes

Quick example

State attributes

Element reference

Top level

Header

Call controls (audio mode)

Action buttons (start screen)

Loading bar

Quick replies and options

Typing indicator

Messages

System log pill

Slash command menu

Voice animation

Interactive flow

Message input (text mode)

Feedback screen

Components

Footer

End-call confirm dialog

Common recipes

Restyle the launcher

Style the muted state

Glow on lit visualizer dots

Italicize agent messages

Hide the footer brand

Wait for the widget to mount

Capture feedback submissions

QA notes