Połączenia web: własny interfejs przez SDK
- Co otrzymasz:
- rozmowa z agentem kampanii na Twojej stronie z takim interfejsem, jakiego potrzebujesz: od jednej linii kodu po własny przycisk, animację i tokeny wydawane przez Twój serwer.
- Co przygotować:
- kampania z włączonymi połączeniami web i dodanymi dozwolonymi witrynami (zob. „Połączenia web: rozmowa z agentem na stronie”), klucz widżetu albo klucz „Tylko połączenia webowe”, dostęp do kodu strony.
Skrypt https://ai.ringostat.com/webcall/v1.js to jednocześnie gotowy widżet i SDK do własnego interfejsu. Wybierz poziom według tego, ile interfejsu chcesz zrobić sam:
| Poziom | Co rysujesz Ty | Klucz |
|---|---|---|
| A. Gotowy widżet | Nic: przycisk, panel i informacje rysuje skrypt, wygląd pochodzi z kreatora w panelu. | Klucz widżetu (publiczny). |
| B. Własny interfejs | Przycisk, stany, animację i informacje; rozmowę prowadzi SDK. | Klucz widżetu (publiczny). |
| C. Własny serwer | To samo co w B, a do tego Twój serwer decyduje, kto dostanie rozmowę. | Klucz „Tylko połączenia webowe” — tylko na serwerze. |
1. Poziom A: gotowy widżet z kreatora
- 1Edytor kampanii → blok „Połączenia web” → „Połączenie” → karta „Widżet” → „Otwórz kreator”.
- 2Wybierz „Jak pokazać”: „Pływający przycisk” (w rogu ekranu), „Blok na stronie” (wewnątrz <div id="ringostat-call">) albo „Własny przycisk” (poziom B, kod od razu z przyciskiem).
- 3Ustaw styl, kolor, tekst przycisku, imię agenta, język i odstępy, zapisz i skopiuj kod. W data-privacy-url podaj swoją politykę prywatności.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<KLUCZ_WIDŻETU>"
data-privacy-url="https://example.com/privacy" async></script>Wygląd jest zapisany w panelu: widżet odczytuje go podczas ładowania (GET /web-call/widget-config, czeka najwyżej 1,5 sekundy i pamięta go przez 5 minut w obrębie karty). Dlatego po zmianach w kreatorze kodu na stronie nie trzeba zmieniać — tylko gdy zmienił się tryb „Jak pokazać”. Jeśli ustawienia się nie wczytają, przycisk pojawi się w standardowym wyglądzie.
Każdy atrybut data w linii nadpisuje to, co zapisano w panelu. Oprócz atrybutów z podstawowego przewodnika (data-lang, data-position, data-color, data-container) wygląd ustawiają:
| Atrybut | Wartości |
|---|---|
| data-style | orb — przycisk z kulą (domyślnie), pill — prosty przycisk, aura — żywa kula jak na naszym landingu (doładowuje v1-aura.js z tego samego miejsca co v1.js). |
| data-size | s, m lub l. |
| data-label | Tekst przycisku, do 40 znaków. Bez niego — standardowy tekst w języku widżetu. |
| data-title | Imię agenta w panelu rozmowy, do 60 znaków. |
| data-palette | Dla aura: default, dental, auto, realestate, shop albo cztery kolory po przecinku "#ciemny,#główny,#miętowy,#błękitny". Bez niego — z data-color. |
| data-motion | Dla aura: calm, normal lub lively. |
| data-offset-x, data-offset-y | Odstęp pływającego przycisku od boku i od dołu, 0–200 px (domyślnie 16). |
Nieznana wartość zostaje zastąpiona domyślną, przezroczystość koloru jest pomijana. Żaden atrybut nie ukrywa informacji o AI i nagrywaniu.
2. Poziom B: własny interfejs przez SDK
Z data-auto="false" skrypt niczego nie rysuje i udostępnia window.RingostatWebCall. Rozmowę (mikrofon, token, dźwięk, wchodzenie w słowo) prowadzi SDK, a przycisk, stany i animację robisz Ty. Tryb „Własny przycisk” w kreatorze generuje właśnie taki kod; poniżej — z czego się składa.
| Wywołanie | Co robi |
|---|---|
| RingostatWebCall.create({ key }) | Nowy obiekt rozmowy. Jeden obiekt to jedna rozmowa: do następnej utwórz nowy. |
| call.start() | Prosi o mikrofon, pobiera token i się łączy. Tylko wewnątrz obsługi kliknięcia, przed jakimkolwiek await. Promise; przy błędzie odrzucany z err.code. |
| call.stop() | Kończy rozmowę po stronie odwiedzającego. |
| call.setMuted(true | false) | Wycisza i włącza mikrofon; agent dostaje ciszę, rozmowa się nie zrywa. |
| call.on(zdarzenie, fn) | Subskrypcja zdarzenia; zwraca funkcję, która ją anuluje. |
| Zdarzenie | Wartość |
|---|---|
| state | { status, agentSpeaking, userSpeaking }; status: idle → connecting → live → ended. |
| transcript | { role: "agent" | "user", text, final, id }: napisy. Dopóki final: false, fraza jest jeszcze doprecyzowywana — zastępuj jej tekst według id, zamiast dopisywać. |
| level | Głośność mikrofonu odwiedzającego, 0..1, około 20 razy na sekundę (0, gdy wyciszony). |
| outputLevel | Głośność głosu agenta, 0..1, około 30 razy na sekundę; 0 na końcu. |
| end | { reason, code? }, dokładnie raz. reason: user_ended — stop(); failed — rozmowa się nie zaczęła; error — błąd serwera; disconnected — zerwane połączenie (bez code); inne — rozmowę zakończył serwer (agent się pożegnał, skończył się czas). code jest, gdy reason to failed lub error. |
Błędy: co pokazać odwiedzającemu
Kod przychodzi w zdarzeniu end (e.code) i w err.code, gdy start() zostanie odrzucony. Wygodnie jest pokazywać komunikaty w jednym miejscu — w end — a start().catch() niech tylko wycisza odrzucenie.
| Kod | Co pokazać odwiedzającemu |
|---|---|
| mic_denied | „Zezwól na dostęp do mikrofonu, aby porozmawiać z agentem” i jak to zrobić: ikona kłódki lub mikrofonu w pasku adresu → zezwól → „Jeszcze raz”. |
| mic_not_found | „Nie znaleziono mikrofonu”: podłącz go albo zamknij program, który go używa. |
| mic_unsupported | „Ta przeglądarka nie daje mikrofonu: otwórz stronę w Safari lub Chrome”. Zdarza się we wbudowanych przeglądarkach Instagrama, Telegrama, Facebooka i w starych przeglądarkach. |
| busy | „Agent jest teraz zajęty, spróbuj za minutę”. W err.retryAfter — po ilu sekundach. |
| rate_limited, daily_limit | „Zbyt wiele prób, spróbuj trochę później”. |
| origin_not_allowed, web_calls_disabled, insufficient_funds | Odwiedzającemu — „Rozmowa jest teraz niedostępna”. To ustawienia panelu: witryny nie ma w „Dozwolone witryny”, połączenia web są wyłączone, brak środków. |
| unavailable, timeout, connect_failed, audio_unavailable; reason disconnected | „Nie udało się połączyć. Spróbuj ponownie”. |
Przykład: własna kula w ~20 liniach
Przycisk, koło, które „oddycha” w rytm głosu agenta (outputLevel), status, wyciszanie i obowiązkowe informacje z linkiem do polityki. Strona działa od razu: wstaw klucz widżetu, adres polityki i dodaj domenę do „Dozwolone witryny”.
<div class="rwc">
<div id="orb" class="orb" aria-hidden="true"></div>
<button id="talk" type="button">Porozmawiaj z agentem</button>
<button id="mute" type="button" hidden>Wycisz mikrofon</button>
<p id="status" role="status" aria-live="polite"></p>
<p class="notice">Rozmawiasz z agentem AI, a nie z człowiekiem. Rozmowa jest nagrywana.
<a href="https://example.com/privacy" target="_blank" rel="noopener">Polityka prywatności</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="<KLUCZ_WIDŻETU>" data-auto="false"></script>
<script>
const ERRORS = {
mic_denied: "Zezwól na dostęp do mikrofonu, aby porozmawiać z agentem.",
mic_not_found: "Nie znaleziono mikrofonu.",
mic_unsupported: "Brak mikrofonu: otwórz stronę w Safari lub Chrome.",
busy: "Agent jest teraz zajęty. Spróbuj za minutę.",
rate_limited: "Zbyt wiele prób. Spróbuj trochę później.",
daily_limit: "Zbyt wiele prób. Spróbuj trochę później.",
};
const FAIL = "Nie udało się połączyć. Spróbuj ponownie.";
const $ = (id) => document.getElementById(id);
let call = null, muted = false;
$("talk").onclick = () => {
if (call) return call.stop(); // drugie kliknięcie kończy rozmowę
call = RingostatWebCall.create({ key: "<KLUCZ_WIDŻETU>" });
call.on("state", (s) => {
$("status").textContent = s.status === "live" ? "Mów, agent słucha" : s.status === "connecting" ? "Łączymy…" : "";
$("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 = "Porozmawiaj z agentem";
$("mute").textContent = "Wycisz mikrofon";
$("status").textContent = e.code ? ERRORS[e.code] || FAIL
: e.reason === "disconnected" ? FAIL : "Dziękujemy za rozmowę!";
});
$("talk").textContent = "Zakończ";
call.start().catch(() => {}); // komunikat pokaże zdarzenie end
};
$("mute").onclick = () => {
muted = !muted;
call && call.setMuted(muted);
$("mute").textContent = muted ? "Włącz mikrofon" : "Wycisz mikrofon";
};
</script>Napisy i wskaźnik mikrofonu: dodaj znaczniki obok przycisku, a subskrypcje — do obsługi $("talk").onclick zaraz po create() (przed kliknięciem call to jeszcze null). Obsługa zdarzeń powinna być krótka i nie rzucać błędów: błąd w obsłudze level zatrzymuje tę ramkę mikrofonu i agent nie usłyszy odwiedzającego.
<!-- znaczniki: obok przycisku -->
<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>
// w obsłudze $("talk").onclick, zaraz po 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. Poziom C: token z Twojego serwera
Gdy rozmowy nie można dawać wszystkim (tylko zalogowanym klientom, po captchy, z Twoim limitem), token wydaje Twój serwer metodą webCall.create z kluczem „Tylko połączenia webowe”. Trzymaj klucz na serwerze; nigdy nie trafia na stronę. Parametry i kody błędów webCall.create są w sekcji „Wariant B: przez Twój serwer” podstawowego przewodnika.
W przeglądarce interfejs jest taki sam jak na poziomie B, tylko zamiast key jest getTicket: funkcja, która zwraca { token, wsUrl } z Twojego serwera. SDK najpierw prosi o mikrofon, potem wywołuje getTicket (token żyje 20 sekund) i się łączy.
<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
// zamiast RingostatWebCall.create({ key }) z przykładu powyżej:
call = RingostatWebCall.create({
getTicket: (signal) =>
fetch("/api/web-call-token", { method: "POST", signal }).then((r) => r.json()),
});
</script>// Serwer (Node.js 18+, Express): POST /api/web-call-token
app.post("/api/web-call-token", async (req, res) => {
// 1. Sprawdź odwiedzającego: Twoja sesja, 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 } }), // publiczny IP odwiedzającego
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 }); // tylko to, nigdy klucz
} catch {
res.status(503).json({ code: "unavailable" }); // Ringostat niedostępny, nie odpowiedział w 10 s albo odpowiedział nie JSON-em
}
});Jeśli getTicket zostanie odrzucony albo zwróci coś innego niż { token, wsUrl } z adresem wss://, rozmowa kończy się kodem unavailable. Powód odmowy (busy, rate_limited) Twój endpoint może zwrócić we własnej odpowiedzi, a strona — pokazać własny tekst. Za proxy bierz clientIp z nagłówka, któremu ufasz (X-Forwarded-For z Twojego load balancera).
4. SPA: React, Next.js, Vue
- Dołącz skrypt raz dla całej aplikacji (index.html, główny layout), a nie w komponencie strony.
- Jeśli router przerysuje body albo kontener, widżet wraca sam. data-container może pojawić się na stronie do 10 sekund po skrypcie.
- RingostatWebCall.unmount() kończy rozmowę, usuwa widżety i przestaje ich pilnować. RingostatWebCall.mount(options?) pokazuje widżet ponownie; options to te same parametry co atrybuty data, w camelCase bez data-: { container: "#talk", offsetX: "24" }. Dopóki widżet jest widoczny, mount() zwraca istniejący, więc aby przenieść go do innego kontenera, najpierw wywołaj unmount().
- v1.js ładuje się asynchronicznie, więc efekt strony albo pierwsza trasa mogą zadziałać przed nim. Dlatego w SPA ustaw data-auto="false" i pokazuj widżet funkcją webCallFor poniżej: czeka na SDK i stosuje to, czego potrzebuje bieżąca trasa, bez „mignięcia” widżetu tam, gdzie go nie powinno być. mount() zwraca Promise z elementem widżetu albo null (powód — w ostrzeżeniu [Ringostat] w konsoli).
// webCallRoute.js — jeden moduł dla całej aplikacji.
// next: false — bez widżetu; undefined — pływający przycisk; { container: "#talk" } — w bloku.
let want, shown, timer, seq = 0;
export async function webCallFor(next) {
want = next;
const w = window.RingostatWebCall;
if (!w || !w.mount) { // v1.js jeszcze się ładuje: zastosujemy, gdy tylko będzie
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; // ten sam tryb: widżet i rozmowa zostają
const my = ++seq; // każde wywołanie ma swój numer: odpowiedź nieaktualnego jest pomijana
shown = key;
w.unmount();
if (want === false) return;
let host = null;
try { host = await w.mount(want); } catch {}
if (!host && my === seq) shown = undefined; // nie pokazano (np. kontenera nie było przez 10 s): następne wywołanie spróbuje ponownie
}// Next.js, app/layout.tsx: skrypt raz; z data-auto="false" widżet pokazuje webCallFor
import Script from "next/script";
<Script src="https://ai.ringostat.com/webcall/v1.js" strategy="afterInteractive"
data-key="<KLUCZ_WIDŻETU>" data-privacy-url="/privacy" data-auto="false" />
// Next.js: komponent kliencki w głównym layoucie decyduje według ścieżki
"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: działa także dla pierwszej trasy
router.afterEach((to) => webCallFor(to.meta.webCall)); // meta: { webCall: false } albo { webCall: { container: "#talk" } }Dla poziomu B w SPA twórz obiekt rozmowy w obsłudze kliknięcia, jak w przykładzie, i wywołuj call.stop() przy opuszczaniu strony (w cleanup efektu lub onBeforeUnmount), żeby rozmowa nie trwała bez interfejsu.
5. Instalacja na stronie
| Gdzie | Jak |
|---|---|
| Własna strona | Wklej kod przed </body> na każdej stronie, na której ma być przycisk (we wspólnym szablonie). |
| Tilda | Ustawienia strony → Więcej → Kod HTML wewnątrz body → wklej kod → zapisz i opublikuj wszystkie strony. Dla „Blok na stronie” dodaj <div id="ringostat-call"></div> blokiem „Kod HTML” (T123) w wybranym miejscu. |
| WordPress | Wtyczka do kodu w header/footer (np. WPCode) → Footer → wklej kod i zapisz. Albo footer.php motywu potomnego przed </body>. |
| Google Tag Manager | Nowy tag „Custom HTML” → wklej kod bez zmian → reguła All Pages → Submit i Publish. Działa, choć GTM uruchamia skrypt bez document.currentScript: widżet sam znajduje swoją linię. Przycisk pojawia się nieco później niż z kodu w szablonie. |
| Wix | Settings → Custom Code → + Add Custom Code → wklej kod, All pages, Place Code in: Body - end. Wymagana podłączona domena. |
| Shopify | Online Store → Themes → … → Edit code → layout/theme.liquid → wklej kod przed </body> → Save. |
Dodaj do „Dozwolone witryny” każdą domenę z kodem, w tym www i adresy testowe kreatora stron (np. project123.tilda.ws): dopasowanie jest dokładne.
6. Wymagania i ograniczenia
- HTTPS. Przeglądarka daje mikrofon tylko bezpiecznym stronom; do programowania wystarczy http://localhost.
- Zgoda na mikrofon. Pierwszy start pokazuje pytanie przeglądarki. W iframe potrzebny jest allow="microphone": <iframe src="…" allow="microphone">; Origin żądania to wtedy domena strony w iframe — ją dodaj do „Dozwolone witryny”.
- Wbudowane przeglądarki (Instagram, Telegram, Facebook) często nie dają mikrofonu: start() kończy się mic_unsupported. Gotowy widżet nie pojawia się na stronach bez mikrofonu (bez HTTPS, bez navigator.mediaDevices, iframe bez allow); we własnym interfejsie ukryj przycisk, jeśli !window.isSecureContext || !navigator.mediaDevices?.getUserMedia.
- Content-Security-Policy — jak w podstawowym przewodniku (script-src https://ai.ringostat.com, connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com). Dla poziomu C dodaj do connect-src adres swojego endpointu (zwykle 'self'). Przy CSP z nonce ustaw nonce na tagu v1.js: v1-aura.js dostanie ten sam.
- Dozwolone witryny: token jest wydawany tylko stronom domen z listy kampanii, dopasowanie jest dokładne.
- Start tylko w kliknięciu: call.start() w obsłudze kliknięcia, nie przy ładowaniu strony i nie po timerze czy długim await. Inaczej przeglądarka nie da mikrofonu ani dźwięku.
- Jeden pływający przycisk na klucz na stronie; duplikat jest pomijany z ostrzeżeniem w konsoli.
- Obowiązkowych informacji o AI i nagrywaniu z linkiem do polityki prywatności nie wyłącza żadne ustawienie; we własnym interfejsie pokazujesz je Ty.
- Czas rozmowy, równoczesne połączenia i limit rozmów z jednego adresu IP — z ustawień kampanii i projektu.
- Nie kopiuj v1.js na swój serwer: wczytywany z ai.ringostat.com aktualizuje się sam. Kopia musi być serwowana z Content-Type: application/javascript; charset=UTF-8 i z v1-aura.js obok, inaczej zepsują się teksty lub styl aura.
Co dalej
- Połączenia web: rozmowa z agentem na stronie — włączenie, klucze, webCall.create, CSP i kody błędów.
- Metody /rpc z przykładami — webCall.create wśród innych metod.
- Webhooki: wyniki połączeń — podsumowanie połączenia web w Twoim CRM.