Skip to main content
Use this quickstart to add a Ringg AI web-call widget to a page. Start with the minimal snippet, verify it in staging, then add branding, chat mode, events, and production controls from the linked reference pages.

Configuration Reference

Load options, variables, positioning, trigger styling, and feedback screens.

Lifecycle Events

Browser events the widget emits about its own state: open/close, conversation start/end, feedback.

Agent Actions

Custom browser events the agent dispatches on the host page, configured under Interactive Components.

Chat and Widgets

Text mode, chat-only embeds, calendar widgets, form widgets, and prompt examples.

Customization

Restyle and script the widget through stable data-ringg attributes.

Production QA and Security

Domain whitelisting, CSP, CDN pinning, browser QA, and launch checks.

​
Prerequisites

An active Ringg AI account.
An assistant configured for Webcall in the Ringg AI dashboard.
The assistant agentId and the widget X-API-KEY from the generated embed code.
Access to add JavaScript to your website HTML or tag manager.
Each staging and production domain added to the assistant’s Whitelist Domains list.
The widget snippet runs in the browser and includes xApiKey. Use only the embed code generated for a web-call assistant, whitelist the exact domains where it can run, and do not expose a broad backend integration key in public pages.

​
Quickstart

1

Configure the assistant for web calls

Open the assistant in the Ringg AI dashboard, go to the WebCall settings, and add your website domain to Whitelist Domains.Add staging domains separately, such as staging.example.com, instead of using one broad production-only assumption.
2

Add the widget snippet

Paste this near the end of the page, preferably before the closing </body> tag. Pick the bundle that matches your host page.
Use dv-agent.es.js when the page is built with Vite, webpack, Next, or any other module-aware setup, or when the snippet runs inside <script type="module">.
<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);
  }

  loadAgentsCdn("latest", function () {
    loadAgent({
      agentId: "your-agent-id",
      xApiKey: "your-api-key",
      variables: {},
      buttons: {},
    });
  });
</script>
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 host page globals like jQuery’s $. Reach for the UMD build on any non-module page.
For production, pin a tested CDN version instead of latest after validating the widget in staging.
3

Set the first configuration options

Keep the first launch small. Add variables and the default mode first, then layer on styling.
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.",
});
4

Update Content Security Policy if needed

If your site uses CSP, allow the widget CDN for scripts and styles.
script-src 'self' https://cdn.jsdelivr.net;
style-src 'self' https://cdn.jsdelivr.net;
If your CSP policy pins exact asset URLs, use the same CDN version in both the loader and the CSP entries.

​
Configuration basics

OptionUse it for
agentIdThe Ringg assistant to load in the widget.
xApiKeyThe widget API key from the dashboard embed code.
variablesRuntime values passed into the assistant prompt, such as names or account IDs.
defaultTab"audio" for voice first or "text" for chat first.
hideTabSelectorSet true for voice-only or chat-only experiences.
buttonsTrigger button and call button styling or labels.
widgetPositionFixed floating widget or absolute placement inside a page container.
See the configuration reference for the full option set and examples.

​
Test checklist

The widget script and stylesheet load without console errors.
The trigger button appears in the expected location on desktop and mobile.
Voice mode asks for microphone permission and can start and end a test call.
Chat mode opens if defaultTab is set to "text".
The domain is whitelisted in the assistant WebCall settings.
Your CSP allows the pinned CDN script and stylesheet.
Events or analytics listeners fire only once per user action.
For launch readiness, use the production QA and security checklist.