Веб-дзвінки: розмова з агентом на сайті
- Що отримаєте:
- відвідувачі вашого сайту говорять з агентом кампанії через мікрофон у браузері, без телефонного номера. Розмова потрапляє в журнал кампанії з позначкою «Веб-дзвінок», звіт, вебхук і Telegram працюють як для телефонних дзвінків.
- Що потрібно заздалегідь:
- кампанія «Голосовий агент» з AI-моделлю реального часу, права адміністратора проєкту і доступ до коду сайту (один рядок для віджета).
1. Увімкніть веб-дзвінки в кампанії
- 1
- 2У «Дозволені сайти» додайте домени, з яких можна почати розмову, напр. shop.example.com. Збіг точний: www.shop.example.com додайте окремим рядком.
- 3За потреби змініть «Розмов з однієї IP-адреси на годину» (за замовчуванням 5).
- 4Залиште «Безпечний режим» увімкненим: відвідувачі анонімні, і в цьому режимі агент не робить записів у календар і не викликає API, навіть якщо їх додано в кампанію.
- 5Натисніть «Зберегти налаштування веб-дзвінків».
Хвилини списуються з балансу або пакета, як за телефонні дзвінки кампанії. Одночасні дзвінки й тривалість розмови — теж за налаштуваннями кампанії та проєкту. Телефонні дії (переведення, передзвін, «не дзвонити», тонові сигнали) у веб-дзвінках недоступні.
2. Варіант А: віджет одним рядком
Найпростіший спосіб: кнопка «Поговорити з агентом» з'являється в кутку сторінки, а все інше робить наш скрипт.
- 1
- 2Скопіюйте рядок кнопкою «Копіювати». Ключ показується лише один раз.
- 3У data-privacy-url вкажіть сторінку політики конфіденційності вашого сайту.
- 4Вставте рядок на сторінки сайту перед </body>.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<КЛЮЧ_ВІДЖЕТА>"
data-privacy-url="/privacy"
data-lang="uk" async></script>| Атрибут | Що задає |
|---|---|
| data-key | Ключ віджета. Обов'язковий. |
| data-privacy-url | Політика конфіденційності сайту, можна відносну адресу (/privacy). Обов'язковий: без нього кнопка не з'явиться. |
| data-lang | Мова кнопки й текстів: uk, en, pl або es. Без нього — мова сторінки (<html lang>), інакше англійська. |
| data-position | right (за замовчуванням) або left: кут сторінки для кнопки. |
| data-color | Колір кнопки, напр. #16c07f (3, 4, 6 або 8 hex-цифр). |
| data-container | CSS-селектор елемента, напр. #talk: кнопка стане в нього замість кута сторінки. Якщо елемент з'являється пізніше (SPA), віджет чекає його до 10 секунд; невалідний селектор — кнопка в куті й попередження в консолі. |
| data-auto="false" | Не показувати нашу кнопку: ви запускаєте розмову своєю (див. нижче). |
Під кнопкою завжди видно «Ви розмовляєте з ШІ-агентом, а не з людиною. Розмова записується.» з посиланням на вашу політику. Натискання відкриває панель із тими самими повідомленнями; розмова починається лише кнопкою в панелі, після дозволу на мікрофон.
Вимоги до сайту
Кнопка з'являється лише там, де браузер дасть мікрофон: сторінка на HTTPS, браузер із navigator.mediaDevices, а в iframe — атрибут allow="microphone". Інакше кнопки немає, а в консолі одне попередження з префіксом [Ringostat]. У вбудованих браузерах Instagram чи Telegram мікрофона може не бути: віджет тоді чесно пише, що треба відкрити сторінку в Safari або Chrome.
Content-Security-Policy: дозвольте script-src https://ai.ringostat.com і connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com. style-src 'unsafe-inline' не потрібен: стилі віджета — це adoptedStyleSheets (у браузерах без них — тег style, якому потрібен 'unsafe-inline').
SPA і конструктори сторінок: якщо фреймворк перемалює сторінку, віджет повернеться сам. Показати чи прибрати його з коду — RingostatWebCall.mount() і RingostatWebCall.unmount() (unmount завершує розмову). mount({ container: "#talk" }) приймає ті самі параметри, що й data-атрибути, без префікса data-. Через Google Tag Manager рядок вставляється тегом «Спеціальний HTML» як є.
Як віджет отримує токен
Ключ віджета не потребує вашого сервера: браузер сам надсилає його на POST /web-call/widget-ticket. Запит приймається лише зі сторінки дозволеного сайту (заголовок Origin), без cookies; тіло — до 8 КБ і лише key та metadata. З однієї IP-адреси — до 20 запитів на хвилину. Відповідь — той самий токен, що й у webCall.create, або помилка з кодом із таблиці нижче та заголовком Retry-After.
POST https://apiagent.ringostat.com/web-call/widget-ticket
Origin: https://shop.example.com
Content-Type: application/json
{ "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":"…" } }Своя кнопка замість нашої
З data-auto="false" скрипт не показує кнопку, а дає об'єкт RingostatWebCall. Почати розмову можна лише всередині натискання користувача: браузер інакше не дасть мікрофон. Повідомлення про ШІ-агента й запис розмови з посиланням на політику тоді показуєте ви, біля своєї кнопки.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<КЛЮЧ_ВІДЖЕТА>" data-auto="false"></script>
<script>
const call = RingostatWebCall.create({ 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 — якщо це помилка
talkButton.onclick = () => call.start().catch((err) => console.log(err.code));
stopButton.onclick = () => call.stop();
muteButton.onclick = () => call.setMuted(true);
</script>Один об'єкт — одна розмова: для наступної створіть новий через RingostatWebCall.create.
3. Варіант Б: через ваш сервер (API)
Для сайтів і застосунків, які самі вирішують, кому дати розмову: лише авторизованим клієнтам, після капчі тощо. Ваш сервер отримує одноразовий токен методом webCall.create і передає його браузеру.
- 1Створіть ключ «Лише веб-дзвінки»: «Налаштування» → «Розширені налаштування» → «+ Створити новий ключ» → доступ ключа «Лише веб-дзвінки», за бажанням — кампанії. Такий ключ уміє лише webCall.create; зберігайте його на сервері й ніколи не вставляйте на сторінку.
- 2Коли відвідувач натиснув вашу кнопку і дав доступ до мікрофона, браузер просить у вашого сервера токен.
- 3Сервер викликає webCall.create з IP-адресою відвідувача й повертає браузеру token і wsUrl. Токен діє 20 секунд і лише один раз.
- 4Браузер підключається до wsUrl з цим токеном і починає розмову.

POST https://apiagent.ringostat.com/rpc
X-API-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":"…" }| Параметр | Що це |
|---|---|
| campaignId | ID кампанії з увімкненими веб-дзвінками. Обов'язковий. |
| clientIp | Публічна IP-адреса відвідувача, як її бачить ваш сервер. Обов'язковий: за нею рахується ліміт розмов на годину. Приватні й локальні адреси не приймаються. |
| externalId | Ваш ідентифікатор (до 128 символів), щоб зв'язати розмову з вашими даними. |
| metadata | Лише ключі page, utm_source, utm_medium, utm_campaign, utm_term, utm_content і source, значення — рядки. Агент їх не бачить; у page адреса без query і #. |
У браузері розмову веде той самий скрипт: замість ключа віджета передайте getTicket — функцію, яка просить токен у вашого сервера. Скрипт спершу просить мікрофон, потім викликає getTicket і підключається.
<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
const call = RingostatWebCall.create({
// ваш endpoint: перевіряє відвідувача і викликає webCall.create
getTicket: () => fetch("/api/web-call-token", { method: "POST" }).then((r) => r.json()),
});
talkButton.onclick = () => call.start(); // події й stop — як у прикладі вище
</script>Без SDK: відкрийте WebSocket на wsUrl з двома підпротоколами: ringostat-web.v1 і token.<token>. Звук мікрофона надсилайте як {"type":"audio","data":<base64>} — PCM16 mono 48 кГц кадрами по 20–40 мс; завершити розмову — {"type":"stop"}. Сервер надсилає audio (той самий формат), state, transcript_ai і transcript_user, а в кінці end з причиною.
Помилки
| Код | Що означає | Що робити |
|---|---|---|
| origin_not_allowed | Сторінка не з дозволеного сайту (віджет). | Додайте домен у «Дозволені сайти», www — окремо. |
| web_calls_disabled | Веб-дзвінки в кампанії вимкнені. | Увімкніть їх у блоці «Веб-дзвінки». |
| busy | Усі одночасні дзвінки кампанії чи проєкту зайняті. | Спробувати через Retry-After секунд; за потреби збільшити одночасні дзвінки. |
| rate_limited | Вичерпано ліміт розмов з однієї IP-адреси чи запитів. | Зачекати retry_after_seconds або підняти ліміт на IP. |
| insufficient_funds | На балансі проєкту немає коштів на дзвінок. | Поповнити баланс чи пакет. |
| not_found | Немає кампанії, вона з іншого проєкту або ключ до неї не прив'язаний. | Перевірте campaignId і кампанії ключа. |
| unavailable | Веб-дзвінки зараз не почнуться: причина під перемикачем у блоці. | Подивіться причину в кабінеті. |
| mic_denied | Відвідувач не дав доступ до мікрофона (лише в браузері). | Попросити дозволити мікрофон для сайту і спробувати ще раз. |
| mic_not_found | Мікрофона немає або його зайняла інша програма. | Підключити мікрофон чи закрити програму, що його тримає. |
| mic_unsupported | Браузер не дає сторінкам мікрофон (вбудований браузер застосунку, старий браузер). | Відкрити сторінку в Safari або Chrome. |
webCall.create повертає код у error.data.code разом із відповідним HTTP-статусом; віджет показує відвідувачу короткий зрозумілий текст замість коду.
Як вимкнути
Вимкніть «Дозволити розмову з агентом у браузері» в кампанії або видаліть ключ: нові розмови не почнуться, активні завершаться.
Що далі
- Веб-дзвінки: свій інтерфейс через SDK — своя кнопка й анімація, SPA, Tilda, WordPress, GTM.
- API і вебхуки — результати веб-дзвінків у вашу CRM.
- Методи /rpc з прикладами — webCall.create серед інших методів.

