Połączenia web: rozmowa z agentem na stronie
- 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
- 2W „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.
- 3W razie potrzeby zmień „Rozmowy z jednego adresu IP na godzinę” (domyślnie 5).
- 4Zostaw 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.
- 5Kliknij „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.
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
- 2Skopiuj linię przyciskiem „Kopiuj”. Klucz jest wyświetlany tylko raz.
- 3W data-privacy-url podaj stronę polityki prywatności Twojej witryny.
- 4Wklej 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>| Atrybut | Co ustawia |
|---|---|
| data-key | Klucz widżetu. Wymagany. |
| data-privacy-url | Polityka prywatności witryny, może być adres względny (/privacy). Wymagany: bez niego przycisk się nie pojawi. |
| data-lang | Język przycisku i tekstów: uk, en, pl lub es. Bez niego — język strony (<html lang>), w innym razie angielski. |
| data-position | right (domyślnie) lub left: róg strony dla przycisku. |
| data-color | Kolor przycisku, np. #16c07f (3, 4, 6 lub 8 cyfr hex). |
| data-container | Selektor 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.
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».
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.
- 1Utwó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ę.
- 2Gdy odwiedzający kliknął Twój przycisk i zezwolił na mikrofon, przeglądarka prosi Twój serwer o token.
- 3Serwer wywołuje webCall.create z adresem IP odwiedzającego i zwraca przeglądarce token i wsUrl. Token działa 20 sekund i tylko raz.
- 4Przeglądarka łączy się z wsUrl z tym tokenem i rozmowa się zaczyna.

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":"…" }| Parametr | Co to jest |
|---|---|
| campaignId | ID kampanii z włączonymi połączeniami web. Wymagany. |
| clientIp | Publiczny 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. |
| externalId | Twój identyfikator (do 128 znaków), aby powiązać rozmowę z Twoimi danymi. |
| metadata | Tylko 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.
Błędy
| Kod | Co oznacza | Co zrobić |
|---|---|---|
| origin_not_allowed | Strona nie jest z dozwolonej witryny (widżet). | Dodaj domenę do „Dozwolone witryny”, www osobno. |
| web_calls_disabled | Połączenia web są w kampanii wyłączone. | Włącz je w bloku „Połączenia web”. |
| busy | Wszystkie 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_limited | Wyczerpany limit rozmów z jednego IP lub zapytań. | Odczekaj retry_after_seconds lub podnieś limit na IP. |
| insufficient_funds | W projekcie brak środków na połączenie. | Doładuj saldo lub pakiet. |
| not_found | Brak kampanii, należy do innego projektu albo klucz nie jest z nią powiązany. | Sprawdź campaignId i kampanie klucza. |
| unavailable | Połączenia web teraz się nie rozpoczną: powód jest pod przełącznikiem w bloku. | Sprawdź powód w panelu. |
| mic_denied | Odwiedzający nie zezwolił na mikrofon (tylko w przeglądarce). | Poproś o zgodę na mikrofon dla witryny i spróbuj ponownie. |
| mic_not_found | Brak mikrofonu albo zajmuje go inna aplikacja. | Podłącz mikrofon lub zamknij aplikację, która go używa. |
| mic_unsupported | Przeglą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
- Połączenia web: własny interfejs przez SDK — własny przycisk i animacja, SPA, Tilda, WordPress, GTM.
- API i webhooki — wyniki połączeń web w Twoim CRM.
- Metody /rpc z przykładami — webCall.create wśród innych metod.

