Web calls: your own interface with the SDK
- What you get:
- a conversation with the campaign's agent on your site with exactly the interface you need: from one line of code to your own button, animation and tokens issued by your server.
- Before you start:
- a campaign with web calls enabled and allowed sites added (see “Web calls: talking to the agent on your site”), a widget key or a “Web calls only” key, access to the site's code.
The script https://ai.ringostat.com/webcall/v1.js is both the ready widget and the SDK for your own interface. Pick a level by how much of the interface you want to build yourself:
| Level | What you draw | Key |
|---|---|---|
| A. Ready widget | Nothing: the script draws the button, the panel and the notices; the look comes from the builder in the cabinet. | Widget key (public). |
| B. Own interface | The button, states, animation and notices; the SDK runs the call. | Widget key (public). |
| C. Own server | The same as B, plus your server decides who gets a conversation. | “Web calls only” key — on the server only. |
1. Level A: the ready widget from the builder
- 1Campaign editor → the “Web calls” block → “Connection” → the “Widget” tab → “Open builder”.
- 2Choose “How to show”: “Floating button” (in the corner of the screen), “Block on the page” (inside <div id="ringostat-call">) or “Own button” (level B, the code already comes with a button).
- 3Set the style, colour, button text, agent name, language and offsets, save and copy the code. Put your privacy policy into data-privacy-url.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<WIDGET_KEY>"
data-privacy-url="https://example.com/privacy" async></script>The look is saved in the cabinet: the widget reads it while loading (GET /web-call/widget-config, waits at most 1.5 seconds and remembers it for 5 minutes within the tab). So after changes in the builder the code on the site stays as it is — only a change of “How to show” needs new code. If the settings do not load, the button appears with the default look.
Any data attribute in the line overrides what is saved in the cabinet. Besides the attributes from the basic guide (data-lang, data-position, data-color, data-container), the look is set by:
| Attribute | Values |
|---|---|
| data-style | orb — a button with a sphere (default), pill — a plain button, aura — the living orb as on our landing (loads v1-aura.js from the same place as v1.js). |
| data-size | s, m or l. |
| data-label | The button's text, up to 40 characters. Without it — the default text in the widget's language. |
| data-title | The agent's name in the call panel, up to 60 characters. |
| data-palette | For aura: default, dental, auto, realestate, shop or four comma-separated colours "#deep,#brand,#mint,#aqua". Without it — from data-color. |
| data-motion | For aura: calm, normal or lively. |
| data-offset-x, data-offset-y | The floating button's distance from the side and from the bottom, 0–200 px (16 by default). |
An unknown value falls back to the default, a colour's transparency is dropped. No attribute hides the AI and recording notices.
2. Level B: your own interface with the SDK
With data-auto="false" the script draws nothing and provides window.RingostatWebCall. The SDK runs the call (microphone, token, audio, barge-in), and you build the button, states and animation. The builder's “Own button” mode generates exactly this kind of code; below is what it is made of.
| Call | What it does |
|---|---|
| RingostatWebCall.create({ key }) | A new conversation object. One object is one conversation: create a new one for the next. |
| call.start() | Asks for the microphone, gets a token and connects. Only inside a click handler, before any await. A Promise; on an error it rejects with err.code. |
| call.stop() | Ends the conversation from the visitor's side. |
| call.setMuted(true | false) | Mutes and unmutes the microphone; the agent gets silence, the call does not drop. |
| call.on(event, fn) | Subscribes to an event; returns a function that unsubscribes. |
| Event | Value |
|---|---|
| state | { status, agentSpeaking, userSpeaking }; status: idle → connecting → live → ended. |
| transcript | { role: "agent" | "user", text, final, id }: subtitles. While final is false the phrase is still being refined — replace its text by id instead of appending. |
| level | The visitor's microphone loudness, 0..1, about 20 times a second (0 while muted). |
| outputLevel | The agent's voice loudness, 0..1, about 30 times a second; 0 at the end. |
| end | { reason, code? }, exactly once. reason: user_ended — stop(); failed — the call did not start; error — a server error; disconnected — the connection dropped (no code); anything else — the server ended the call (the agent said goodbye, the duration ran out). code is there when reason is failed or error. |
Errors: what to show the visitor
The code comes in the end event (e.code) and in err.code when start() rejects. It is handy to show messages in one place — in end — and let start().catch() only swallow the rejection.
| Code | What to show the visitor |
|---|---|
| mic_denied | “Allow microphone access to talk to the agent” and how: the lock or microphone icon in the address bar → allow → “Again”. |
| mic_not_found | “No microphone found”: connect one or close the app that is using it. |
| mic_unsupported | “This browser gives no microphone: open the page in Safari or Chrome”. Happens in the in-app browsers of Instagram, Telegram, Facebook and in old browsers. |
| busy | “The agent is busy right now, try again in a minute”. err.retryAfter says in how many seconds. |
| rate_limited, daily_limit | “Too many attempts, please try again a bit later”. |
| origin_not_allowed, web_calls_disabled, insufficient_funds | To the visitor — “Conversation is unavailable right now”. These are cabinet settings: the site is not in “Allowed sites”, web calls are off, no funds. |
| unavailable, timeout, connect_failed, audio_unavailable; reason disconnected | “Could not connect. Please try again”. |
Example: your own orb in ~20 lines
A button, a circle that “breathes” with the agent's voice (outputLevel), a status line, mute and the required notices with the policy link. The page works as is: put in your widget key, policy address and add the domain to “Allowed sites”.
<div class="rwc">
<div id="orb" class="orb" aria-hidden="true"></div>
<button id="talk" type="button">Talk to the agent</button>
<button id="mute" type="button" hidden>Mute</button>
<p id="status" role="status" aria-live="polite"></p>
<p class="notice">You are talking to an AI agent, not a person. The call is recorded.
<a href="https://example.com/privacy" target="_blank" rel="noopener">Privacy policy</a></p>
</div>
<style>
.orb { width: 96px; height: 96px; margin: 24px; border-radius: 50%; pointer-events: none;
background: radial-gradient(circle at 35% 30%, #c6f7de, #16c07f 55%, #0a6646); transition: transform .1s; }
.notice { font-size: 12px; color: #6b7686; }
</style>
<script src="https://ai.ringostat.com/webcall/v1.js" data-key="<WIDGET_KEY>" data-auto="false"></script>
<script>
const ERRORS = {
mic_denied: "Allow microphone access to talk to the agent.",
mic_not_found: "No microphone found.",
mic_unsupported: "No microphone here: open the page in Safari or Chrome.",
busy: "The agent is busy right now. Try again in a minute.",
rate_limited: "Too many attempts. Please try again a bit later.",
daily_limit: "Too many attempts. Please try again a bit later.",
};
const FAIL = "Could not connect. Please try again.";
const $ = (id) => document.getElementById(id);
let call = null, muted = false;
$("talk").onclick = () => {
if (call) return call.stop(); // the second click ends the call
call = RingostatWebCall.create({ key: "<WIDGET_KEY>" });
call.on("state", (s) => {
$("status").textContent = s.status === "live" ? "Speak, the agent is listening" : s.status === "connecting" ? "Connecting…" : "";
$("mute").hidden = s.status !== "live";
});
call.on("outputLevel", (v) => { $("orb").style.transform = "scale(" + (1 + v * 0.4) + ")"; });
call.on("end", (e) => {
call = null; muted = false;
$("talk").textContent = "Talk to the agent";
$("mute").textContent = "Mute";
$("status").textContent = e.code ? ERRORS[e.code] || FAIL
: e.reason === "disconnected" ? FAIL : "Thanks for the conversation!";
});
$("talk").textContent = "End call";
call.start().catch(() => {}); // the end event shows the message
};
$("mute").onclick = () => {
muted = !muted;
call && call.setMuted(muted);
$("mute").textContent = muted ? "Unmute" : "Mute";
};
</script>Subtitles and a microphone meter: add the markup next to the button and the subscriptions to the $("talk").onclick handler right after create() (before the click call is still null). Event handlers should be short and must not throw: an error in the level handler stops that microphone frame, and the agent will not hear the visitor.
<!-- markup: next to the button -->
<p id="caption" aria-live="polite"></p>
<div style="height: 4px; background: #e6e6e6"><div id="mic" style="height: 4px; width: 0; background: #16c07f"></div></div>
// in the $("talk").onclick handler, right after call = RingostatWebCall.create(...):
call.on("transcript", (t) => { if (t.role === "agent") $("caption").textContent = t.text; });
call.on("level", (v) => {
const mic = $("mic");
if (mic) mic.style.width = Math.round(v * 100) + "%";
});3. Level C: a token from your server
When not everyone should get a conversation (only signed-in customers, after a captcha, with your own limit), your server issues the token with webCall.create and a “Web calls only” key. Keep the key on the server; it never reaches the page. The parameters and error codes of webCall.create are in the “Option B: through your server” section of the basic guide.
In the browser the interface is the same as in level B, only instead of key there is getTicket: a function that returns { token, wsUrl } from your server. The SDK asks for the microphone first, then calls getTicket (the token lives 20 seconds) and connects.
<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
// instead of RingostatWebCall.create({ key }) in the example above:
call = RingostatWebCall.create({
getTicket: (signal) =>
fetch("/api/web-call-token", { method: "POST", signal }).then((r) => r.json()),
});
</script>// Server (Node.js 18+, Express): POST /api/web-call-token
app.post("/api/web-call-token", async (req, res) => {
// 1. Check the visitor: your session, captcha, limit.
try {
const r = await fetch("https://apiagent.ringostat.com/rpc", {
method: "POST",
headers: { "Content-Type": "application/json", "X-API-Key": process.env.RINGOSTAT_WEB_CALLS_KEY },
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "webCall.create",
params: { campaignId: 799, clientIp: req.ip } }), // the visitor's public IP
signal: AbortSignal.timeout(10000),
});
const { result, error } = await r.json();
if (!result) return res.status(503).json({ code: (error && error.data && error.data.code) || "unavailable" });
res.json({ token: result.token, wsUrl: result.wsUrl }); // only this, never the key
} catch {
res.status(503).json({ code: "unavailable" }); // Ringostat is unreachable, did not answer in 10 s or answered with something other than JSON
}
});If getTicket rejects or returns something other than { token, wsUrl } with a wss:// address, the call ends with the code unavailable. Your endpoint can return the refusal reason (busy, rate_limited) in its own answer, and the page can show its own text. Behind a proxy take clientIp from a header you trust (X-Forwarded-For from your load balancer).
4. SPA: React, Next.js, Vue
- Include the script once for the whole app (index.html, the root layout), not in a page component.
- If the router re-renders the body or the container, the widget comes back by itself. data-container may appear on the page up to 10 seconds after the script.
- RingostatWebCall.unmount() ends the call, removes the widgets and stops watching them. RingostatWebCall.mount(options?) shows the widget again; options are the same as the data attributes, in camelCase without data-: { container: "#talk", offsetX: "24" }. While a widget is shown, mount() returns the existing one, so to move it into another container call unmount() first.
- v1.js loads asynchronously, so a page's effect or the first route may run before it. So in an SPA set data-auto="false" and show the widget with the webCallFor function below: it waits for the SDK and applies what the current route needs, with no “flash” of the widget where it should not be. mount() returns a Promise with the widget's element or null (the reason is in a [Ringostat] warning in the console).
// webCallRoute.js — one module for the whole app.
// next: false — no widget; undefined — the floating button; { container: "#talk" } — in a block.
let want, shown, timer, seq = 0;
export async function webCallFor(next) {
want = next;
const w = window.RingostatWebCall;
if (!w || !w.mount) { // v1.js is still loading: apply as soon as it is there
timer = timer || setInterval(() => {
if (window.RingostatWebCall && window.RingostatWebCall.mount) { clearInterval(timer); timer = 0; webCallFor(want); }
}, 100);
return;
}
const key = JSON.stringify(want === undefined ? null : want);
if (key === shown) return; // the same mode: the widget and the call stay
const my = ++seq; // every call gets its number: a stale call's answer is ignored
shown = key;
w.unmount();
if (want === false) return;
let host = null;
try { host = await w.mount(want); } catch {}
if (!host && my === seq) shown = undefined; // not shown (e.g. no container within 10 s): the next call tries again
}// Next.js, app/layout.tsx: the script once; with data-auto="false" webCallFor shows the widget
import Script from "next/script";
<Script src="https://ai.ringostat.com/webcall/v1.js" strategy="afterInteractive"
data-key="<WIDGET_KEY>" data-privacy-url="/privacy" data-auto="false" />
// Next.js: a client component in the root layout decides by the path
"use client";
import { useEffect } from "react";
import { usePathname } from "next/navigation";
import { webCallFor } from "./webCallRoute";
export function WebCallRoute() {
const path = usePathname();
useEffect(() => {
webCallFor(path.startsWith("/checkout") ? false : path === "/contacts" ? { container: "#talk" } : undefined);
}, [path]);
return null;
}
// Vue Router: runs for the first route too
router.afterEach((to) => webCallFor(to.meta.webCall)); // meta: { webCall: false } or { webCall: { container: "#talk" } }For level B in an SPA, create the call object in the click handler as in the example, and call call.stop() when leaving the page (in the effect's cleanup or onBeforeUnmount), so the call does not go on without an interface.
5. Installing on the site
| Where | How |
|---|---|
| Your own site | Paste the code before </body> on every page that needs the button (in the shared template). |
| Tilda | Site settings → More → HTML code for the body → paste the code → save and publish all pages. For “Block on the page” add <div id="ringostat-call"></div> with an “HTML code” block (T123) where it should be. |
| WordPress | A plugin for header/footer code (e.g. WPCode) → Footer → paste the code and save. Or the child theme's footer.php before </body>. |
| Google Tag Manager | A new “Custom HTML” tag → paste the code as is → the All Pages trigger → Submit and Publish. It works although GTM runs the script without document.currentScript: the widget finds its line itself. The button appears a bit later than with the code in the template. |
| Wix | Settings → Custom Code → + Add Custom Code → paste the code, All pages, Place Code in: Body - end. A connected domain is required. |
| Shopify | Online Store → Themes → … → Edit code → layout/theme.liquid → paste the code before </body> → Save. |
Add every domain with the code to “Allowed sites”, including www and the site builder's test addresses (e.g. project123.tilda.ws): the match is exact.
6. Requirements and limits
- HTTPS. Browsers give the microphone to secure pages only; http://localhost is fine for development.
- Microphone permission. The first start shows the browser's prompt. An iframe needs allow="microphone": <iframe src="…" allow="microphone">; the request's Origin is then the framed page's domain — add that one to “Allowed sites”.
- In-app browsers (Instagram, Telegram, Facebook) often give no microphone: start() ends with mic_unsupported. The ready widget does not appear on pages without a microphone (no HTTPS, no navigator.mediaDevices, an iframe without allow); in your own interface hide the button if !window.isSecureContext || !navigator.mediaDevices?.getUserMedia.
- Content-Security-Policy — as in the basic guide (script-src https://ai.ringostat.com, connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com). For level C add your endpoint's address to connect-src (usually 'self'). With a nonce-based CSP put the nonce on the v1.js tag: v1-aura.js gets the same one.
- Allowed sites: a token is issued only to pages of the domains on the campaign's list, the match is exact.
- Start only in a click: call.start() goes in a click handler, not on page load and not after a timer or a long await. Otherwise the browser gives neither the microphone nor audio.
- One floating button per key per page; a duplicate is ignored with a warning in the console.
- The mandatory AI and recording notices with the privacy policy link cannot be turned off by any setting; in your own interface you show them.
- Call duration, concurrent calls and the limit of conversations per IP address come from the campaign and project settings.
- Do not copy v1.js to your server: loaded from ai.ringostat.com it updates itself. A copy must be served with Content-Type: application/javascript; charset=UTF-8 and with v1-aura.js next to it, otherwise the texts or the aura style break.
What next
- Web calls: talking to the agent on your site — enabling, keys, webCall.create, CSP and error codes.
- /rpc methods with examples — webCall.create among the other methods.
- Webhooks: call results — a web call's summary into your CRM.