Ringostat
Zaloguj

Połączenia web: rozmowa z agentem na stronie

~7 min · Przycisk „Porozmawiaj z agentem” na Twojej stronie: widżet w jednej linii albo własna integracja przez API.
Co otrzymasz:
odwiedzający Twoją stronę rozmawiają z agentem kampanii przez mikrofon w przeglądarce, bez numeru telefonu. Rozmowa trafia do dziennika kampanii z oznaczeniem „Połączenie webowe”, a raport, webhook i Telegram działają jak dla połączeń telefonicznych.
Co przygotować:
kampania „Agent głosowy” z modelem AI czasu rzeczywistego, uprawnienia administratora projektu i dostęp do kodu strony (jedna linia dla widżetu).

1. Włącz połączenia web w kampanii

  1. 1
    Edytor kampanii → blok „Połączenia web” → „Pozwól odwiedzającym rozmawiać z agentem w przeglądarce”.
    Blok „Połączenia web”
    Blok „Połączenia web”
  2. 2
    W „Dozwolone witryny” dodaj domeny, z których można rozpocząć rozmowę, np. shop.example.com. Dopasowanie jest dokładne: www.shop.example.com dodaj osobno.
  3. 3
    W razie potrzeby zmień „Rozmowy z jednego adresu IP na godzinę” (domyślnie 5).
  4. 4
    Zostaw włączony „Tryb bezpieczny”: odwiedzający są anonimowi, a w tym trybie agent nie zapisuje niczego w kalendarzu i nie wywołuje API, nawet jeśli dodano je do kampanii.
  5. 5
    Kliknij „Zapisz ustawienia połączeń web”.

Minuty są pobierane z salda lub pakietu tak jak za połączenia telefoniczne kampanii. Połączenia jednoczesne i czas rozmowy również zależą od ustawień kampanii i projektu. Działania telefoniczne (przekierowanie, oddzwonienie, „nie dzwonić”, sygnały tonowe) w połączeniach web nie są dostępne.

Jeśli blok pokazuje, dlaczego połączenia web teraz się nie rozpoczną (model nie działa w czasie rzeczywistym, brak witryn, kampania w archiwum itp.), najpierw to popraw. Członek projektu widzi blok, ale może tylko zawężać dostęp: wyłączyć połączenia albo włączyć tryb bezpieczny.

2. Wariant A: widżet w jednej linii

Najprostszy sposób: w rogu strony pojawia się przycisk „Porozmawiaj z agentem”, a resztę robi nasz skrypt.

  1. 1
    W bloku „Połączenia web” → „Połączenie” otwórz kartę „Widżet” i kliknij „Utwórz klucz widżetu”.
    Karta „Widżet”
    Karta „Widżet”
  2. 2
    Skopiuj linię przyciskiem „Kopiuj”. Klucz jest wyświetlany tylko raz.
  3. 3
    W data-privacy-url podaj stronę polityki prywatności Twojej witryny.
  4. 4
    Wklej linię na strony witryny przed </body>.
<script src="https://ai.ringostat.com/webcall/v1.js"
        data-key="<KLUCZ_WIDŻETU>"
        data-privacy-url="/privacy"
        data-lang="pl" async></script>
data-keyKlucz widżetu. Wymagany.
data-privacy-urlPolityka prywatności witryny, może być adres względny (/privacy). Wymagany: bez niego przycisk się nie pojawi.
data-langJęzyk przycisku i tekstów: uk, en, pl lub es. Bez niego — język strony (<html lang>), w innym razie angielski.
data-positionright (domyślnie) lub left: róg strony dla przycisku.
data-colorKolor przycisku, np. #16c07f (3, 4, 6 lub 8 cyfr hex).
data-containerSelektor CSS elementu, np. #talk: przycisk trafi do niego zamiast do rogu strony. Jeśli element pojawia się później (SPA), widżet czeka na niego do 10 sekund; nieprawidłowy selektor — przycisk w rogu i ostrzeżenie w konsoli.
data-auto="false"Bez naszego przycisku: rozmowę uruchamiasz własnym (zob. niżej).

Pod przyciskiem zawsze widać „Rozmawiasz z agentem AI, a nie z człowiekiem. Rozmowa jest nagrywana.” z linkiem do Twojej polityki. Kliknięcie otwiera panel z tymi samymi informacjami; rozmowa zaczyna się dopiero przyciskiem w panelu, po zgodzie na mikrofon.

Skrypt ładuje się z naszej domeny, więc aktualizacje trafiają na Twoją stronę same. Niezgodne zmiany wyjdą jako v2.js, a v1.js dalej będzie działać.

Wymagania wobec strony

Przycisk pojawia się tylko tam, gdzie przeglądarka da mikrofon: strona na HTTPS, przeglądarka z navigator.mediaDevices, a w iframe atrybut allow="microphone". W przeciwnym razie przycisku nie ma, a w konsoli jest jedno ostrzeżenie z prefiksem [Ringostat]. Wbudowane przeglądarki Instagrama czy Telegrama mogą nie mieć mikrofonu: widżet napisze wtedy, by otworzyć stronę w Safari lub Chrome.

Content-Security-Policy: zezwól na script-src https://ai.ringostat.com i connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com. style-src 'unsafe-inline' nie jest potrzebny: style widżetu to adoptedStyleSheets (przeglądarki bez nich dostają znacznik style, który wymaga 'unsafe-inline').

SPA i kreatory stron: gdy framework przerysuje stronę, widżet wróci sam. Aby pokazać lub usunąć go z kodu, wywołaj RingostatWebCall.mount() i RingostatWebCall.unmount() (unmount kończy rozmowę). mount({ container: "#talk" }) przyjmuje te same ustawienia co atrybuty data, bez prefiksu data-. W Google Tag Manager wklej wiersz bez zmian do tagu «Niestandardowy kod HTML».

Klucz widżetu jest publiczny: widać go w kodzie strony. Potrafi tylko jedno: rozpocząć połączenie web tej kampanii ze strony dozwolonej witryny. Odwołać go można na stronie kluczy API.

Jak widżet otrzymuje token

Klucz widżetu nie wymaga Twojego serwera: przeglądarka sama wysyła go na POST /web-call/widget-ticket. Zapytanie jest przyjmowane tylko ze strony dozwolonej witryny (nagłówek Origin), bez cookies; treść — do 8 KB i tylko key oraz metadata. Z jednego adresu IP — do 20 zapytań na minutę. Odpowiedź to ten sam token co z webCall.create albo błąd z kodem z tabeli poniżej i nagłówkiem Retry-After.

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

{ "key":"<KLUCZ_WIDŻETU>", "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":"…" } }

Własny przycisk zamiast naszego

Z data-auto="false" skrypt nie pokazuje przycisku, tylko udostępnia obiekt RingostatWebCall. Rozmowę można rozpocząć wyłącznie w kliknięciu użytkownika: inaczej przeglądarka nie da mikrofonu. Informację o agencie AI i nagrywaniu z linkiem do polityki pokazujesz wtedy sam, obok swojego przycisku.

<script src="https://ai.ringostat.com/webcall/v1.js"
        data-key="<KLUCZ_WIDŻETU>" data-auto="false"></script>
<script>
  const call = RingostatWebCall.create({ key: "<KLUCZ_WIDŻETU>" });
  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 — gdy to błąd
  talkButton.onclick = () => call.start().catch((err) => console.log(err.code));
  stopButton.onclick = () => call.stop();
  muteButton.onclick = () => call.setMuted(true);
</script>

Jeden obiekt to jedna rozmowa: do następnej utwórz nowy przez RingostatWebCall.create.

3. Wariant B: przez Twój serwer (API)

Dla stron i aplikacji, które same decydują, komu dać rozmowę: tylko zalogowanym klientom, po captchy itp. Twój serwer pobiera jednorazowy token metodą webCall.create i przekazuje go przeglądarce.

  1. 1
    Utwórz klucz „Tylko połączenia webowe”: „Ustawienia” → „Ustawienia zaawansowane” → „+ Wygeneruj nowy klucz” → dostęp klucza „Tylko połączenia webowe”, opcjonalnie kampanie. Taki klucz potrafi tylko webCall.create; trzymaj go na serwerze i nigdy nie wstawiaj na stronę.
  2. 2
    Gdy odwiedzający kliknął Twój przycisk i zezwolił na mikrofon, przeglądarka prosi Twój serwer o token.
  3. 3
    Serwer wywołuje webCall.create z adresem IP odwiedzającego i zwraca przeglądarce token i wsUrl. Token działa 20 sekund i tylko raz.
  4. 4
    Przeglądarka łączy się z wsUrl z tym tokenem i rozmowa się zaczyna.
Karta „API”: przykład zapytania dla tej kampanii
Karta „API”: przykład zapytania dla tej kampanii
POST https://apiagent.ringostat.com/rpc
X-API-Key: <KLUCZ_POŁĄCZEŃ_WEB>
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 kampanii z włączonymi połączeniami web. Wymagany.
clientIpPubliczny adres IP odwiedzającego, tak jak widzi go Twój serwer. Wymagany: według niego liczony jest godzinny limit na IP. Adresy prywatne i lokalne są odrzucane.
externalIdTwój identyfikator (do 128 znaków), aby powiązać rozmowę z Twoimi danymi.
metadataTylko klucze page, utm_source, utm_medium, utm_campaign, utm_term, utm_content i source, wartości — tekst. Agent ich nie widzi; page zapisywany jest bez query i #.

W przeglądarce rozmowę prowadzi ten sam skrypt: zamiast klucza widżetu przekaż getTicket — funkcję, która prosi Twój serwer o token. Skrypt najpierw prosi o mikrofon, potem wywołuje getTicket i się łączy.

<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
  const call = RingostatWebCall.create({
    // Twój endpoint: sprawdza odwiedzającego i wywołuje webCall.create
    getTicket: () => fetch("/api/web-call-token", { method: "POST" }).then((r) => r.json()),
  });
  talkButton.onclick = () => call.start(); // zdarzenia i stop — jak w przykładzie wyżej
</script>

Bez SDK: otwórz WebSocket do wsUrl z dwoma podprotokołami: ringostat-web.v1 i token.<token>. Dźwięk mikrofonu wysyłaj jako {"type":"audio","data":<base64>}: PCM16 mono 48 kHz w ramkach 20–40 ms; zakończ rozmowę przez {"type":"stop"}. Serwer wysyła audio (ten sam format), state, transcript_ai i transcript_user, a na końcu end z powodem.

Zabezpiecz adres swojego serwera, który wydaje tokeny: własną sesją, captchą lub limitem. Sprawdzenie witryny (Origin) nie jest uwierzytelnieniem: skrypt może je podrobić. Proś o mikrofon przed pobraniem tokenu: token żyje tylko 20 sekund.

Błędy

origin_not_allowedStrona nie jest z dozwolonej witryny (widżet).Dodaj domenę do „Dozwolone witryny”, www osobno.
web_calls_disabledPołączenia web są w kampanii wyłączone.Włącz je w bloku „Połączenia web”.
busyWszystkie jednoczesne połączenia kampanii lub projektu są zajęte.Spróbuj po Retry-After sekundach; w razie potrzeby zwiększ liczbę jednoczesnych połączeń.
rate_limitedWyczerpany limit rozmów z jednego IP lub zapytań.Odczekaj retry_after_seconds lub podnieś limit na IP.
insufficient_fundsW projekcie brak środków na połączenie.Doładuj saldo lub pakiet.
not_foundBrak kampanii, należy do innego projektu albo klucz nie jest z nią powiązany.Sprawdź campaignId i kampanie klucza.
unavailablePołączenia web teraz się nie rozpoczną: powód jest pod przełącznikiem w bloku.Sprawdź powód w panelu.
mic_deniedOdwiedzający nie zezwolił na mikrofon (tylko w przeglądarce).Poproś o zgodę na mikrofon dla witryny i spróbuj ponownie.
mic_not_foundBrak mikrofonu albo zajmuje go inna aplikacja.Podłącz mikrofon lub zamknij aplikację, która go używa.
mic_unsupportedPrzeglądarka nie daje stronom mikrofonu (wbudowana w aplikację lub stara).Otwórz stronę w Safari lub Chrome.

webCall.create zwraca kod w error.data.code wraz z odpowiednim statusem HTTP; widżet pokazuje odwiedzającemu krótki zrozumiały tekst zamiast kodu.

Jak wyłączyć

Wyłącz „Pozwól odwiedzającym rozmawiać z agentem w przeglądarce” w kampanii albo usuń klucz: nowe rozmowy się nie rozpoczną, trwające się zakończą.

Co dalej