Ringostat
Log in

Web calls: talking to the agent on your site

~7 min · A “Talk to the agent” button on your site: a one-line widget or your own integration through the API.
What you get:
visitors of your site talk to the campaign's agent through the microphone in the browser, with no phone number. The conversation lands in the campaign's call log marked “Web call”; the report, webhook and Telegram work as for phone calls.
Before you start:
a “Voice Agent” campaign with a realtime AI model, project admin rights and access to your site's code (one line for the widget).

1. Turn web calls on in the campaign

  1. 1
    Campaign editor → the “Web calls” block → “Let visitors talk to the agent in the browser”.
    The Web calls block
    The Web calls block
  2. 2
    Under “Allowed sites”, add the domains a conversation may start from, e.g. shop.example.com. The match is exact: add www.shop.example.com as a separate line.
  3. 3
    If needed, change “Calls from one IP address per hour” (5 by default).
  4. 4
    Keep “Safe mode” on: visitors are anonymous, and in this mode the agent books nothing in calendars and calls no APIs, even if they are added to the campaign.
  5. 5
    Click “Save web call settings”.

Minutes are charged to the balance or package as for the campaign's phone calls. Simultaneous calls and call duration also follow the campaign and project settings. Phone actions (transfer, callback, “do not call”, tones) are never available in web calls.

If the block says why web calls will not start right now (not a realtime model, no sites, an archived campaign and so on), fix that first. A project member sees the block but can only narrow access: switch calls off or turn safe mode on.

2. Option A: a one-line widget

The simplest way: a “Talk to the agent” button appears in a corner of the page, and our script does the rest.

  1. 1
    In the “Web calls” block → “Connection”, open the “Widget” tab and click “Create a widget key”.
    The Widget tab
    The Widget tab
  2. 2
    Copy the line with “Copy”. The key is shown only once.
  3. 3
    Put your site's privacy policy page into data-privacy-url.
  4. 4
    Paste the line into your site's pages before </body>.
<script src="https://ai.ringostat.com/webcall/v1.js"
        data-key="<WIDGET_KEY>"
        data-privacy-url="/privacy"
        data-lang="en" async></script>
data-keyThe widget key. Required.
data-privacy-urlYour site's privacy policy; a relative address (/privacy) works. Required: without it no button is shown.
data-langLanguage of the button and texts: uk, en, pl or es. Without it, the page's language (<html lang>), else English.
data-positionright (default) or left: the page corner for the button.
data-colorButton colour, e.g. #16c07f (3, 4, 6 or 8 hex digits).
data-containerA CSS selector, e.g. #talk: the button goes into that element instead of the page corner. If the element appears later (an SPA), the widget waits for it up to 10 seconds; an invalid selector puts the button in the corner with a console warning.
data-auto="false"No button of ours: you start the conversation from your own (see below).

Under the button the visitor always sees “You are talking to an AI agent, not a person. The call is recorded.” with a link to your policy. A click opens a panel with the same notices; the conversation starts only from the panel's button, after the microphone is allowed.

The script loads from our domain, so updates reach your site on their own. Incompatible changes will ship as v2.js, and v1.js keeps working.

Site requirements

The button shows only where the browser can give a microphone: an HTTPS page, a browser with navigator.mediaDevices, and in an iframe the allow="microphone" attribute. Otherwise there is no button and one console warning prefixed [Ringostat]. In-app browsers (Instagram, Telegram) may have no microphone: the widget then says to open the page in Safari or Chrome.

Content-Security-Policy: allow script-src https://ai.ringostat.com and connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com. No style-src 'unsafe-inline' is needed: the widget's styles are adoptedStyleSheets (browsers without them get a style tag, which needs 'unsafe-inline').

SPAs and page builders: when the framework re-renders the page, the widget comes back on its own. To show or remove it from code, call RingostatWebCall.mount() and RingostatWebCall.unmount() (unmount ends a call). mount({ container: "#talk" }) takes the same settings as the data attributes, without the data- prefix. In Google Tag Manager, paste the line as is into a Custom HTML tag.

The widget key is public: it is visible in the page code. It can do one thing only: start a web call of this campaign from a page of an allowed site. You can revoke it on the API keys page.

How the widget gets its token

A widget key needs no server of yours: the browser sends it to POST /web-call/widget-ticket itself. The request is accepted only from a page of an allowed site (the Origin header), without cookies; the body is up to 8 KB with only key and metadata. One IP address may send up to 20 requests a minute. The answer is the same token as from webCall.create, or an error with a code from the table below and a Retry-After header.

POST https://apiagent.ringostat.com/web-call/widget-ticket
Origin: https://shop.example.com
Content-Type: application/json

{ "key":"<WIDGET_KEY>", "metadata":{ "page":"https://shop.example.com/pricing" } }

→ 200 { "ok":true, "ticket":{ "token":"wct1.…", "wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
        "expiresIn":20, "maxDurationSec":180, "callId":"…" } }
→ 403 { "ok":false, "error":{ "code":"origin_not_allowed", "message":"…" } }

Your own button instead of ours

With data-auto="false" the script shows no button and gives you the RingostatWebCall object. A conversation can start only inside the user's click: otherwise the browser will not give the microphone. Show the AI agent and recording notices with the policy link yourself, next to your button.

<script src="https://ai.ringostat.com/webcall/v1.js"
        data-key="<WIDGET_KEY>" data-auto="false"></script>
<script>
  const call = RingostatWebCall.create({ key: "<WIDGET_KEY>" });
  call.on("state", (s) => console.log(s.status));      // connecting → live → ended
  call.on("transcript", (t) => console.log(t.role, t.text));
  call.on("end", (e) => console.log(e.reason, e.code)); // code: when it is an error
  talkButton.onclick = () => call.start().catch((err) => console.log(err.code));
  stopButton.onclick = () => call.stop();
  muteButton.onclick = () => call.setMuted(true);
</script>

One object is one conversation: create a new one with RingostatWebCall.create for the next.

3. Option B: through your server (API)

For sites and apps that decide themselves who gets a conversation: signed-in customers only, after a captcha and so on. Your server gets a one-time token with webCall.create and hands it to the browser.

  1. 1
    Create a “Web calls only” key: “Settings” → “Advanced settings” → “+ Generate New Key” → key access “Web calls only”, optionally with campaigns. Such a key can only call webCall.create; keep it on your server and never put it into a page.
  2. 2
    When the visitor clicked your button and allowed the microphone, the browser asks your server for a token.
  3. 3
    The server calls webCall.create with the visitor's IP address and returns token and wsUrl to the browser. The token lives 20 seconds and works once.
  4. 4
    The browser connects to wsUrl with this token and the conversation starts.
The API tab: a request example for this campaign
The API tab: a request example for this campaign
POST https://apiagent.ringostat.com/rpc
X-API-Key: <WEB_CALLS_KEY>
Content-Type: application/json

{ "jsonrpc":"2.0", "id":1, "method":"webCall.create",
  "params":{ "campaignId":799, "clientIp":"203.0.113.7",
    "externalId":"order-1842",
    "metadata":{ "page":"https://shop.example.com/pricing", "utm_source":"google" } } }

→ "result": { "token":"wct1.…", "wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
  "expiresIn":20, "maxDurationSec":180, "callId":"…" }
campaignIdID of a campaign with web calls on. Required.
clientIpThe visitor's public IP address as your server sees it. Required: the hourly per-IP limit counts by it. Private and local addresses are refused.
externalIdYour own ID (up to 128 characters) to tie the conversation to your data.
metadataOnly the keys page, utm_source, utm_medium, utm_campaign, utm_term, utm_content and source, string values. The agent never sees them; page is stored without the query and #.

In the browser, the same script runs the conversation: pass getTicket instead of a widget key, a function that asks your server for the token. The script asks for the microphone first, then calls getTicket and connects.

<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
  const call = RingostatWebCall.create({
    // your endpoint: it checks the visitor and calls webCall.create
    getTicket: () => fetch("/api/web-call-token", { method: "POST" }).then((r) => r.json()),
  });
  talkButton.onclick = () => call.start(); // events and stop: as in the example above
</script>

Without the SDK: open a WebSocket to wsUrl with two subprotocols: ringostat-web.v1 and token.<token>. Send the microphone as {"type":"audio","data":<base64>}: PCM16 mono 48 kHz in 20–40 ms frames; end the conversation with {"type":"stop"}. The server sends audio (same format), state, transcript_ai and transcript_user, and end with the reason at the end.

Protect your server's token address: with your own session, a captcha or a limit. The site check (Origin) is not authentication: a script can forge it. Ask for the microphone before requesting the token: the token lives only 20 seconds.

Errors

origin_not_allowedThe page is not on an allowed site (widget).Add the domain to “Allowed sites”, www separately.
web_calls_disabledWeb calls are off in the campaign.Turn them on in the “Web calls” block.
busyAll simultaneous calls of the campaign or project are taken.Retry after Retry-After seconds; raise simultaneous calls if needed.
rate_limitedThe per-IP or request limit is used up.Wait retry_after_seconds or raise the per-IP limit.
insufficient_fundsThe project has no funds for a call.Top up the balance or package.
not_foundNo such campaign, it belongs to another project, or the key is not bound to it.Check campaignId and the key's campaigns.
unavailableWeb calls will not start right now: the reason is under the switch in the block.See the reason in the cabinet.
mic_deniedThe visitor did not allow the microphone (browser only).Ask to allow the microphone for the site and try again.
mic_not_foundNo microphone, or another app holds it.Connect a microphone or close the app that uses it.
mic_unsupportedThe browser gives pages no microphone (an in-app or old browser).Open the page in Safari or Chrome.

webCall.create returns the code in error.data.code with the matching HTTP status; the widget shows the visitor a short plain text instead of the code.

How to switch off

Turn off “Let visitors talk to the agent in the browser” in the campaign or delete the key: new conversations will not start, live ones end.

What next