Web widget configuration reference

loadAgent takes one object that controls how the web widget looks and starts on your page. The agent’s prompt, voice and tools stay in the dashboard. Settings from the Appearance tab in Web widget overview are written into the copied snippet as these same fields. Options marked 2.0 need a 2.0.0-beta CDN version. See Pick a CDN version.

CDN bundles

The CDN exposes loadAgent on window once the script has loaded. Two builds are published:

Bundle	Use it on
`dv-agent.es.js`	Pages built with Vite, webpack or Next.js, or code inside `<script type="module">`.
`dv-agent.umd.js`	jQuery pages, legacy CMS themes and any page that loads plain `<script>` tags.

The ES build loaded as a plain <script> puts its internals on window and can overwrite globals such as jQuery’s $. The snippet copied from the dashboard loads the ES build as a plain script, so on a non-module page change the file name to dv-agent.umd.js.

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

    const script = document.createElement("script");
    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>

Full example

loadAgentsCdn("1.0.21", function () {
  loadAgent({
    agentId: "your-agent-id",
    authorization: "Bearer your-webcall-public-key",
    variables: { callee_name: "Priya", loan_id: "AL-1042" },
    defaultTab: "audio",
    title: "Acme Lending support",
    description: "Ask about your EMI or start a call.",
    theme: { primaryColor: "#2563eb", buttonStyle: "pill" },
    buttons: {
      modalTrigger: { styles: { backgroundColor: "#2563eb", borderRadius: "50%" } },
      call: { textBeforeCall: "Talk to us" },
    },
    widgetPosition: { triggerAlignment: "bottom-right", widgetAlignment: "bottom-right" },
  });
});

Core options

variables, the key and everything else in this object are readable in the page source. Never put passwords, internal tokens or personal data in them.

string

required

The agent to load.

string

required

Bearer <webcall-public-key>, from the dashboard snippet.

object

default:"{}"

Values for the agent’s variables, such as callee_name.

"audio" | "text"

default:"audio"

"audio" opens on voice, "text" on chat.

boolean

default:"false"

true shows only the defaultTab mode.

boolean

default:"false"

A trigger click starts the defaultTab conversation directly. From 1.0.20.

boolean

default:"false"

Skips the rating screen after a conversation. 2.0

boolean

default:"false"

Opens the panel on page load. 2.0

string

default:"Ringg AI Support"

Start-screen heading.

string

Start-screen text under the title. Defaults to Ringg’s copy.

string

Logo in the header. From 1.0.10.

{ text, links }

Replaces the privacy and terms text shown before a conversation. Words in text that match a key in links link to that URL.

string[]

Words cycled while a reply is pending. 2.0

object

Colors and corners. See Theme.

object

default:"{}"

Trigger and start buttons. See Buttons.

Fixed, bottom right by default. See Position.

object

Panel size, 400 × 456 px by default (95% of the screen width on mobile). See Window size.

object

Ringg copy and 5 stars by default. See Feedback screen.

{ enabled, showIds }

default:"{ enabled: false }"

Shows a pill in the chat each time an agent action fires. 2.0

Theme

Every color accepts a hex value or a CSS gradient string. Components inherit these values.

string

Buttons, selected states, the trigger and the typing shimmer.

string

Text on primaryColor.

string

Panel background.

string

Cards, inputs and the visitor’s message bubble.

string

Puts agent messages in a bubble of this color. Unset, they render as plain text. 2.0

string

Body text.

string

Secondary text.

string

Borders and dividers.

string

Error states.

string

Success states.

string

Corner radius of the panel, cards and inputs, for example "20px".

"rounded" | "pill" | "square"

Button corner style.

Buttons

buttons: {
  modalTrigger: {
    styles: { backgroundColor: "#2563eb", width: 64, height: 64, borderRadius: "50%" },
    icon: { url: "https://www.acme-lending.example/chat-icon.svg", size: 28 },
  },
  call: { textBeforeCall: "Talk to us" },
  text: { textBeforeCall: "Message us" },
},

CSS properties for the floating trigger.

Trigger icon image. Defaults to the Ringg phone icon.

Icon width and height in pixels. 25 on 1.0.

string

default:"Start Call"

Label on the start-call button.

string

default:"Start Chat"

Label on the start-chat button.

On 2.0, when both buttons show side by side, the defaults shorten to Call and Chat.

Position

From 1.0.19.

"fixed" floats over the viewport. "absolute" places the widget inside the ringg_ai_container element.

"center", "top-left", "top-right", "bottom-left" or "bottom-right".

"bottom-left", "bottom-center" or "bottom-right".

Hides the trigger while the panel is open.

For absolute placement, add the container before loadAgent runs and give it a height. Without it, the widget creates ringg_ai_container at the end of <body>.

<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" },
});

Window size

innerWindowProps sets the open panel’s width, height and borderRadius. Numbers are pixels; strings pass through as CSS. The Size controls in Appearance allow width 280–600 px, height 300–700 px and radius 0–40 px.

innerWindowProps: { width: 420, height: 560, borderRadius: 16 },

Feedback screen

Shown after a conversation ends, unless bypassFeedbackScreen is true. A submitted or skipped rating fires ringg:feedback_status; see Events.

feedbackScreen: {
  title: "How was your call?",
  description: "Your rating helps us improve.",
  starsCount: 5,
  submitBtnCTA: "Send",
},

string

Heading above the stars.

string

Text under the heading.

number

default:"5"

Number of stars. Appearance offers 3 to 5.

{ filledColor, emptyColor }

Star colors.

string

Comment box placeholder.

string

Submit button label.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Web widget configuration

CDN bundles

Full example

Core options

Theme

Buttons

Position

Window size

Feedback screen

​CDN bundles

​Full example

​Core options

​Theme

​Buttons

​Position

​Window size

​Feedback screen

CDN bundles

Full example

Core options

Theme

Buttons

Position

Window size

Feedback screen