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",
    xApiKey: "your-api-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.
`xApiKey`	`string`	Required	Widget API key from the dashboard embed code.
`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`	Hides the audio/text tab switcher for a single-mode experience. 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 widget.
`buttons`	`object`	`{}`	Trigger and call button customization.
`widgetPosition`	`object`	Fixed bottom-right	Placement rules for the trigger and expanded widget.
`feedbackScreen`	`object`	Unset	Text for the post-conversation feedback screen.

Variables

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

loadAgent({
  agentId: "your-agent-id",
  xApiKey: "your-api-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",
  xApiKey: "your-api-key",
  defaultTab: "audio",
  hideTabSelector: false,
});

loadAgent({
  agentId: "your-chat-agent-id",
  xApiKey: "your-api-key",
  defaultTab: "text",
  hideTabSelector: false,
});

loadAgent({
  agentId: "your-chat-agent-id",
  xApiKey: "your-api-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",
  xApiKey: "your-api-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",
  xApiKey: "your-api-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",
  xApiKey: "your-api-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",
  xApiKey: "your-api-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",
  xApiKey: "your-api-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.

​CDN loader

​Base configuration

​Core options

​Variables

​Mode controls

​Widget positioning

​Trigger button customization

​Call button labels

​Feedback screen

CDN loader

Base configuration

Core options

Variables

Mode controls

Widget positioning

Trigger button customization

Call button labels

Feedback screen