Embed a Ringg AI Voice and Chat Widget on Your Website

The web widget puts an agent on your site as a floating button that opens a voice call or a text chat in the visitor’s browser. For a native app, use the React Native or Flutter package instead. In the dashboard: Assistants → your agent → Embed & Widgets. Its Install & domains and Appearance tabs are covered here; Components has its own page.

What this chapter covers

Page	Read it when
This page	You are installing the widget for the first time.
Configuration	You want to change what the panel says, how it looks, or where it sits.
Events	Your analytics or page should react when a conversation starts or ends.
Chat mode	Visitors should type instead of talk.
Components, Data, Recipes	The agent should show forms, cards and slot pickers in the chat.
Styling	You need CSS or JavaScript hooks the options don’t cover.
Launch checklist	You are about to go to production.

Before you start

An agent

A Webcall agent, or any voice agent. WhatsApp agents can’t be embedded.

Access to the page HTML

Or your tag manager.

Every visitor can read the snippet. It authenticates with the agent’s webcall public key (authorization: "Bearer <key>"), which works only for that agent and only from the origins under Allowed clients. Every agent has a webcall key. If the page could not load it, the generated snippet shows xApiKey: "YOUR_API_KEY" instead; reload the page to get the key. Never fill that in with your workspace API key: it is not limited to one agent or to your domains, and anyone could copy it from the page.

Components, Appearance and Install & domains

Allow your domains

In Install & domains, add each site under Allowed clients, for example www.acme-lending.example and staging.acme-lending.example. Separate several entries with commas. A page whose origin is not on the list cannot start a conversation, which is the usual reason an embed works on staging and fails in production.

Pick a CDN version

The version selector on the snippet lists every published version, newest first, and starts on the newest.

Version	What you get
`1.0.x` (the npm `latest` tag)	Voice and chat, theme, buttons, positioning, feedback screen, lifecycle events.
`2.0.0-beta.x`	Everything in 1.0, plus Components, agent actions, `data-ringg` attributes, `typingWords`, `agentBubbleColor` and `eventLogs`. Beta builds can change between releases.

loadAgentsCdn("latest", …) resolves to the 1.0 line. Use it only while exploring, and ship an exact version you have tested.

Copy the snippet

Click Copy and paste the code before the closing </body> tag. The snippet already contains your agentId, the webcall key, the agent’s variables and any Appearance settings. It follows this pattern:

Widget snippet

<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.es.js`;

    document.head.appendChild(stylesheet);
    document.head.appendChild(script);
  }

  loadAgentsCdn("1.0.21", function () {
    loadAgent({
      agentId: "your-agent-id",
      authorization: "Bearer your-webcall-public-key",
      variables: { callee_name: "Priya", loan_id: "AL-1042" },
    });
  });
</script>

The snippet loads dv-agent.es.js as a plain <script>, which can overwrite page globals such as jQuery’s $. On a non-module page use dv-agent.umd.js (CDN bundles).

If no trigger button appears, check that the script and stylesheet loaded without console errors and that loadAgent runs inside the loadAgentsCdn callback.

Allow the CDN in your CSP

If your site sends a Content Security Policy, allow https://cdn.jsdelivr.net in script-src and style-src; to pin exact files, see CSP setup.

The trigger button appears at the bottom right. Clicking it opens the start screen; starting a call asks for microphone permission, then connects to the agent. The call appears in Logs with call type Webcall.

Hand the install to Claude, Cursor or ChatGPT. Fill in the two placeholders first.

Open in Cursor

Building a Flutter app? Choose Flutter above the snippet instead of Web, add the ringg_flutter package (mobile guide, Flutter view), then create the controller where your app starts. Replace clientOrigin with your real application ID and add the same string to Allowed clients (use ios:// for the iOS build).

Allowed clients

“Only these websites and apps can run your agent.” Each entry is an . Type an entry and press Enter or Add. Separate several entries with commas.

Entry	Example	Shown under
A website	`https://www.example.com` or `example.com`	Websites
An app, by application ID	`android://com.example.app`, `ios://com.example.app`	Mobile apps

https://www.ringg.ai is listed by default (tagged default) and cannot be removed.
capacitor://localhost, ionic://localhost and file:// are tagged shared: every app built on that runtime presents the same origin, so allowing one admits all of them.
A bare host is saved as https://<host>, so example.com becomes https://example.com. www.example.com and example.com are different origins; add both if your site answers on both.
Ports, localhost and IP addresses are allowed, for example http://localhost:3000. Wildcards (*.example.com) and paths are not.
Ringg checks each entry when you save. A rejected entry stays in the field with the reason underneath.
Each change saves immediately (“Allowed clients updated successfully.”). Click × on an entry to remove it.

For and staging tips, see Production QA and security.

Appearance

Set the widget’s theme, size and branding before you copy the snippet. A live preview sits beside the settings on single-prompt agents. To style the widget further in code, see Configuration and Customization.

Setting	Options	Default
Theme	Light, Purple, Blue, Green, or Custom colors… (Primary, Background, Surface, Text, Border, as hex)	Dark grey primary on an off-white background
Size: Width	280–600 px, steps of 10	400 px
Size: Height	300–700 px, steps of 10	456 px
Size: Radius	0–40 px	16 px
Branding	Title, Description, Logo URL (logo needs widget v1.0.10 or later)	Empty
Feedback screen	Title, Description, Placeholder, Submit Button Text, Stars count (3–5), star colours Filled and Empty	5 stars, `#FBBF24` filled, `#D1D5DB` empty

Widget appearance with the Blue theme selected, size 400 by 456 px, radius 16, branding title Acme Lending Help, and a live preview of the chat widget — Appearance with the live preview

Appearance settings are not saved on the agent. They are written into the Web snippet on Install & domains, so copy the snippet before you leave the section and keep it in your own code. The Flutter snippet does not include them.

Common options

Pass these in the loadAgent object. The full list is in the configuration reference.

Option	Use it for
`variables`	Values the agent’s prompt reads, such as `callee_name`. Visible to anyone who views the page source.
`defaultTab`	`"audio"` opens on voice (default), `"text"` opens on chat.
`hideTabSelector`	`true` shows only the `defaultTab` mode.
`title`, `description`, `logoUrl`	Start-screen copy and logo.
`theme`, `buttons`, `widgetPosition`	Colors, the trigger button and placement.

Rotate the webcall key

Click Rotate key above the snippet and confirm Rotate. The old key stops working immediately, so every live embed fails until you copy the new snippet and redeploy. Rotate when the key has been used from somewhere it shouldn’t have been, and schedule the redeploy for the same window.

With the API

Edit Assistant sets Allowed clients with operation: "edit_agent_whitelisted_domains" and the list of origins in whitelisted_domains. The list replaces the saved one, so send every origin each time. It must still include https://www.ringg.ai, or the request fails with 400 “Ringg.ai domain cannot be removed!” You need an API key and the agent ID.

cURL

curl -X PATCH "https://prod-api.ringg.ai/ca/api/v0/agent/v1" \
  -H "X-API-KEY: $RINGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-0000000000a1",
    "operation": "edit_agent_whitelisted_domains",
    "whitelisted_domains": ["https://www.ringg.ai", "https://www.example.com", "android://com.example.app"]
  }'

Set components, appearance and the webcall key in the dashboard.

Troubleshooting

The widget loads but will not connect

"Please enter a website or app"

The field was empty when you clicked Add.

Next steps

Configure the widget

Panel copy, theme, trigger button, position and window size.

Listen for events

Send conversation starts, ends and ratings to your analytics.

Prepare for launch

Domains, CSP, version pinning and browser QA before production.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Web widget

What this chapter covers

Before you start

An agent

Access to the page HTML

Install the widget

Allowed clients

Appearance

Common options

Rotate the webcall key

With the API

Troubleshooting

Next steps

Configure the widget

Listen for events

Prepare for launch

​What this chapter covers

​Before you start

An agent

Access to the page HTML

​Install the widget

​Allowed clients

​Appearance

​Common options

​Rotate the webcall key

​With the API

​Troubleshooting

​Next steps

Configure the widget

Listen for events

Prepare for launch

What this chapter covers

Before you start

Install the widget

Allowed clients

Appearance

Common options

Rotate the webcall key

With the API

Troubleshooting

Next steps