Ringostat
Zaloguj

Połączenia web: własny interfejs przez SDK

~12 min · Dla programistów: gotowy widżet, własny przycisk i animacja na bazie SDK albo w całości przez Twój serwer. SPA, instalacja, wymagania.
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:

A. Gotowy widżetNic: przycisk, panel i informacje rysuje skrypt, wygląd pochodzi z kreatora w panelu.Klucz widżetu (publiczny).
B. Własny interfejsPrzycisk, stany, animację i informacje; rozmowę prowadzi SDK.Klucz widżetu (publiczny).
C. Własny serwerTo 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

  1. 1
    Edytor kampanii → blok „Połączenia web” → „Połączenie” → karta „Widżet” → „Otwórz kreator”.
  2. 2
    Wybierz „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).
  3. 3
    Ustaw 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ą:

data-styleorb — 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-sizes, m lub l.
data-labelTekst przycisku, do 40 znaków. Bez niego — standardowy tekst w języku widżetu.
data-titleImię agenta w panelu rozmowy, do 60 znaków.
data-paletteDla aura: default, dental, auto, realestate, shop albo cztery kolory po przecinku "#ciemny,#główny,#miętowy,#błękitny". Bez niego — z data-color.
data-motionDla aura: calm, normal lub lively.
data-offset-x, data-offset-yOdstę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.

Język. Jeśli na stronie jest już starsza linia z atrybutem data-lang, nadpisuje ona język z kreatora. Po zmianie języka w kreatorze jednorazowo zastąp starą linię nową — inaczej język się nie zmieni.
Ten sam klucz dwa razy jako pływający przycisk (linia i w motywie, i w GTM) daje jeden widżet, a w konsoli ostrzeżenie „duplicate snippet ignored”. Bloków na stronie (data-container) może być kilka.

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.

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.
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ć.
levelGłośność mikrofonu odwiedzającego, 0..1, około 20 razy na sekundę (0, gdy wyciszony).
outputLevelGł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.

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_fundsOdwiedzają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) + "%";
});
Informacje „Rozmawiasz z agentem AI, a nie z człowiekiem” i „Rozmowa jest nagrywana” z linkiem do polityki prywatności są obowiązkowe (EU AI Act, art. 50) i muszą być widoczne przy przycisku przed rozpoczęciem rozmowy. We własnym interfejsie odpowiadasz za nie Ty: nie ukrywaj ich, nie zmniejszaj poniżej 12 px i nie usuwaj ze stron z przyciskiem.

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

Własna stronaWklej kod przed </body> na każdej stronie, na której ma być przycisk (we wspólnym szablonie).
TildaUstawienia 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.
WordPressWtyczka do kodu w header/footer (np. WPCode) → Footer → wklej kod i zapisz. Albo footer.php motywu potomnego przed </body>.
Google Tag ManagerNowy 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.
WixSettings → Custom Code → + Add Custom Code → wklej kod, All pages, Place Code in: Body - end. Wymagana podłączona domena.
ShopifyOnline 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