Embedding Widget Configuration

This page covers the frontend configuration object passed to loadAgent. Configure assistant behavior, tools, and widget metadata in the Ringg AI dashboard; use this object for page-level runtime settings.

CDN loader

The widget script exposes loadAgent after the CDN bundle finishes loading. Two builds are published: pick the one that matches how your host page loads JavaScript.

Bundle	When to use
`dv-agent.es.js`	Module-aware setups: Vite, webpack, Next, or anything loaded inside `<script type="module">`.
`dv-agent.umd.js`	jQuery pages, legacy CMS themes, and any host page that loads scripts with a plain `<script>` tag.

The ES bundle is only safe inside module-aware setups. Loading dv-agent.es.js as a plain <script> leaks internals onto window and can clobber globals like jQuery’s $, which breaks the host page. Use dv-agent.umd.js on any non-module page.

ES build (module-aware)
UMD build (jQuery or legacy)

<script type="module">
  function loadAgentsCdn(version, done) {
    const stylesheet = document.createElement("link");
    stylesheet.rel = "stylesheet";
    stylesheet.type = "text/css";
    stylesheet.href = `https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@${version}/dist/style.css`;

    const script = document.createElement("script");
    script.type = "module";
    script.onload = done;
    script.src = `https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@${version}/dist/dv-agent.es.js`;

    document.head.appendChild(stylesheet);
    document.head.appendChild(script);
  }
</script>

<script>
  function loadAgentsCdn(version, done) {
    const stylesheet = document.createElement("link");
    stylesheet.rel = "stylesheet";
    stylesheet.type = "text/css";
    stylesheet.href = `https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@${version}/dist/style.css`;

    const script = document.createElement("script");
    script.type = "text/javascript";
    script.onload = done;
    script.src = `https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@${version}/dist/dv-agent.umd.js`;

    document.head.appendChild(stylesheet);
    document.head.appendChild(script);
  }
</script>

Use latest while exploring in development. For production, pin the tested CDN version and update CSP entries to match the bundle (dv-agent.es.js or dv-agent.umd.js) you ship.

Base configuration

loadAgentsCdn("latest", function () {
  loadAgent({
    agentId: "your-agent-id",
    authorization: "Bearer your-webcall-public-key",
    variables: {
      callee_name: "John",
      account_id: "ACC-42",
    },
    defaultTab: "audio",
    hideTabSelector: false,
    title: "Talk to our assistant",
    description: "Ask a question or start a voice call.",
    buttons: {
      modalTrigger: {
        styles: {
          backgroundColor: "#4F46E5",
          color: "white",
          borderRadius: "50%",
        },
      },
      call: {
        textBeforeCall: "Start Call",
        textDuringCall: "End Call",
      },
    },
    widgetPosition: {
      triggerPlacement: "fixed",
      triggerAlignment: "bottom-right",
      hideTriggerOnExpand: true,
      widgetAlignment: "bottom-right",
    },
  });
});

Core options

Option	Type	Default	Description
`agentId`	`string`	Required	Assistant ID to load in the widget.
`authorization`	`string`	Required	`Bearer <webcall-public-key>`. The webcall public key is generated for the assistant in the dashboard embed code and can be rotated from there.
`variables`	`object`	`{}`	Runtime variables available to the assistant.
`defaultTab`	`"audio" \| "text"`	`"audio"`	Tab shown when the widget loads. Use `"text"` for chat mode. Supported from v1.0.8+.
`hideTabSelector`	`boolean`	`false`	Pins the widget to `defaultTab` (single-mode start screen). Supported from v1.0.8+.
`bypassStartScreen`	`boolean`	`false`	Skips the start screen and begins a call or chat immediately on trigger click. Uses `defaultTab`.
`title`	`string`	Unset	Heading shown in the widget start screen.
`description`	`string`	Unset	Supporting copy shown in the widget start screen.
`logoUrl`	`string`	Unset	Logo image URL shown in the header and, when set, the launcher.
`typingWords`	`string[]`	`["Thinking", "Reasoning", "Working on it", "Almost there"]`	Words cycled in the pending-reply indicator (shimmered, “Thinking…” style).
`theme`	`object`	Unset	Widget color theme (see below).
`buttons`	`object`	`{}`	Trigger and call button customization.
`widgetPosition`	`object`	Fixed bottom-right	Placement rules for the trigger and expanded widget.
`feedbackScreen`	`object`	Unset	Text and star colors for the post-conversation feedback screen.

Theme

Pass theme to color the widget. Colors accept a solid value or a CSS gradient string.

Field	Description
`theme.primaryColor`	Accent for buttons, selected states, the launcher, and the shimmer.
`theme.primaryTextColor`	Text on the primary color.
`theme.backgroundColor`	Widget background.
`theme.surfaceColor`	Cards, inputs, and the user message bubble.
`theme.agentBubbleColor`	When set, agent messages render inside a bubble with this background (accepts a gradient). Unset = agent messages are bubble-less plain text.
`theme.textColor` / `theme.mutedTextColor`	Body and secondary text.
`theme.borderColor`	Borders and dividers.
`theme.errorColor` / `theme.successColor`	Validation, danger, and success states.
`theme.borderRadius`	Corner radius for the panel, cards, and inputs.
`theme.buttonStyle`	`"pill"` / `"rounded"` / `"square"` — button corner style.

Variables

Use variables for page-specific context that the assistant prompt expects.

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  variables: {
    callee_name: "John",
    account_id: "ACC-42",
    plan_name: "Enterprise",
  },
});

Variables are sent from the browser. Do not put secrets, internal tokens, or sensitive data in the widget configuration.

Mode controls

Voice first
Chat first
Single mode

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  defaultTab: "audio",
  hideTabSelector: false,
});

loadAgent({
  agentId: "your-chat-agent-id",
  authorization: "Bearer your-webcall-public-key",
  defaultTab: "text",
  hideTabSelector: false,
});

loadAgent({
  agentId: "your-chat-agent-id",
  authorization: "Bearer your-webcall-public-key",
  defaultTab: "text",
  hideTabSelector: true,
});

For chat setup, see Chat and Widgets. Positioning controls are supported from v1.0.19+.

Fixed mode
Absolute mode

Fixed mode is the default. The trigger floats over the page and is anchored to the browser viewport.

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  widgetPosition: {
    triggerPlacement: "fixed",
    triggerAlignment: "bottom-right",
    hideTriggerOnExpand: true,
    widgetAlignment: "bottom-right",
  },
});

Absolute mode embeds the widget inside a page container. The container must exist before loadAgent runs and should have an explicit height.

<div id="ringg_ai_container" style="position: relative; width: 100%; height: 500px;"></div>

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  widgetPosition: {
    triggerPlacement: "absolute",
    triggerAlignment: "center",
  },
});

Option	Type	Default	Description
`triggerPlacement`	`string`	`"fixed"`	Use `"fixed"` for viewport placement or `"absolute"` for the `ringg_ai_container` container.
`triggerAlignment`	`string`	`"bottom-right"`	Trigger button position.
`hideTriggerOnExpand`	`boolean`	`true`	Hides the trigger button when the widget is open.
`widgetAlignment`	`string`	`"bottom-right"`	Expanded widget position.

Trigger button customization

Trigger button customization is supported from v1.0.19+.

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  buttons: {
    modalTrigger: {
      styles: {
        backgroundColor: "#4F46E5",
        color: "white",
        width: 64,
        height: 64,
        borderRadius: "50%",
      },
      icon: {
        url: "https://example.com/my-icon.svg",
        size: 24,
      },
    },
  },
});

Option	Type	Default	Description
`buttons.modalTrigger.styles`	`CSSProperties`	Unset	Button CSS styles, such as `width`, `height`, `backgroundColor`, `color`, and `borderRadius`.
`buttons.modalTrigger.icon.url`	`string`	Ringg phone icon	Custom trigger icon URL.
`buttons.modalTrigger.icon.size`	`number`	`20`	Icon size in pixels.

Call button labels

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  buttons: {
    call: {
      textBeforeCall: "Start Call",
      textDuringCall: "End Call",
    },
  },
});

Feedback screen

Use feedbackScreen to customize the post-conversation feedback copy.

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  feedbackScreen: {
    title: "How was your chat?",
    description: "Your feedback helps us improve!",
    submitBtnCTA: "Submit",
  },
});

Option	Type	Description
`feedbackScreen.title`	`string`	Title shown on the feedback screen.
`feedbackScreen.description`	`string`	Supporting feedback copy.
`feedbackScreen.submitBtnCTA`	`string`	Text for the submit button.

Get Started

API Reference

Webhooks Setup

Telephony Integration

External Integrations

Embedding Widget Configuration

CDN loader

Base configuration

Core options

Theme

Variables

Mode controls

Widget positioning

Trigger button customization

Call button labels

Feedback screen

​CDN loader

​Base configuration

​Core options

​Theme

​Variables

​Mode controls

​Widget positioning

​Trigger button customization

​Call button labels

​Feedback screen

CDN loader

Base configuration

Core options

Theme

Variables

Mode controls

Widget positioning

Trigger button customization

Call button labels

Feedback screen