Ringostat
Вхід

Веб-дзвінки: розмова з агентом на сайті

~7 хв · Кнопка «Поговорити з агентом» на вашому сайті: віджет одним рядком або власна інтеграція через API.
Що отримаєте:
відвідувачі вашого сайту говорять з агентом кампанії через мікрофон у браузері, без телефонного номера. Розмова потрапляє в журнал кампанії з позначкою «Веб-дзвінок», звіт, вебхук і Telegram працюють як для телефонних дзвінків.
Що потрібно заздалегідь:
кампанія «Голосовий агент» з AI-моделлю реального часу, права адміністратора проєкту і доступ до коду сайту (один рядок для віджета).

1. Увімкніть веб-дзвінки в кампанії

  1. 1
    Редактор кампанії → блок «Веб-дзвінки» → «Дозволити розмову з агентом у браузері».
    Блок «Веб-дзвінки»
    Блок «Веб-дзвінки»
  2. 2
    У «Дозволені сайти» додайте домени, з яких можна почати розмову, напр. shop.example.com. Збіг точний: www.shop.example.com додайте окремим рядком.
  3. 3
    За потреби змініть «Розмов з однієї IP-адреси на годину» (за замовчуванням 5).
  4. 4
    Залиште «Безпечний режим» увімкненим: відвідувачі анонімні, і в цьому режимі агент не робить записів у календар і не викликає API, навіть якщо їх додано в кампанію.
  5. 5
    Натисніть «Зберегти налаштування веб-дзвінків».

Хвилини списуються з балансу або пакета, як за телефонні дзвінки кампанії. Одночасні дзвінки й тривалість розмови — теж за налаштуваннями кампанії та проєкту. Телефонні дії (переведення, передзвін, «не дзвонити», тонові сигнали) у веб-дзвінках недоступні.

Якщо під перемикачем написано, чому веб-дзвінки зараз не почнуться (модель не реального часу, немає сайтів, кампанію в архіві тощо), спершу виправте це. Учасник проєкту бачить блок, але може лише звужувати доступ: вимкнути дзвінки чи увімкнути безпечний режим.

2. Варіант А: віджет одним рядком

Найпростіший спосіб: кнопка «Поговорити з агентом» з'являється в кутку сторінки, а все інше робить наш скрипт.

  1. 1
    У блоці «Веб-дзвінки» → «Підключення» відкрийте вкладку «Віджет» і натисніть «Створити ключ віджета».
    Вкладка «Віджет»
    Вкладка «Віджет»
  2. 2
    Скопіюйте рядок кнопкою «Копіювати». Ключ показується лише один раз.
  3. 3
    У data-privacy-url вкажіть сторінку політики конфіденційності вашого сайту.
  4. 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-positionright (за замовчуванням) або left: кут сторінки для кнопки.
data-colorКолір кнопки, напр. #16c07f (3, 4, 6 або 8 hex-цифр).
data-containerCSS-селектор елемента, напр. #talk: кнопка стане в нього замість кута сторінки. Якщо елемент з'являється пізніше (SPA), віджет чекає його до 10 секунд; невалідний селектор — кнопка в куті й попередження в консолі.
data-auto="false"Не показувати нашу кнопку: ви запускаєте розмову своєю (див. нижче).

Під кнопкою завжди видно «Ви розмовляєте з ШІ-агентом, а не з людиною. Розмова записується.» з посиланням на вашу політику. Натискання відкриває панель із тими самими повідомленнями; розмова починається лише кнопкою в панелі, після дозволу на мікрофон.

Скрипт завантажується з нашого домену, тому оновлення приходять на ваш сайт самі. Несумісні зміни вийдуть як v2.js, а v1.js продовжить працювати.

Вимоги до сайту

Кнопка з'являється лише там, де браузер дасть мікрофон: сторінка на 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» як є.

Ключ віджета публічний, його видно в коді сторінки. Він уміє лише одне: почати веб-дзвінок цієї кампанії зі сторінки дозволеного сайту. Відкликати ключ можна на сторінці API-ключів.

Як віджет отримує токен

Ключ віджета не потребує вашого сервера: браузер сам надсилає його на 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. 1
    Створіть ключ «Лише веб-дзвінки»: «Налаштування» → «Розширені налаштування» → «+ Створити новий ключ» → доступ ключа «Лише веб-дзвінки», за бажанням — кампанії. Такий ключ уміє лише webCall.create; зберігайте його на сервері й ніколи не вставляйте на сторінку.
  2. 2
    Коли відвідувач натиснув вашу кнопку і дав доступ до мікрофона, браузер просить у вашого сервера токен.
  3. 3
    Сервер викликає webCall.create з IP-адресою відвідувача й повертає браузеру token і wsUrl. Токен діє 20 секунд і лише один раз.
  4. 4
    Браузер підключається до wsUrl з цим токеном і починає розмову.
Вкладка «API»: приклад запиту для цієї кампанії
Вкладка «API»: приклад запиту для цієї кампанії
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":"…" }
campaignIdID кампанії з увімкненими веб-дзвінками. Обов'язковий.
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) не є автентифікацією, її можна підробити зі скрипта. Просіть мікрофон до запиту токена: токен живе лише 20 секунд.

Помилки

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-статусом; віджет показує відвідувачу короткий зрозумілий текст замість коду.

Як вимкнути

Вимкніть «Дозволити розмову з агентом у браузері» в кампанії або видаліть ключ: нові розмови не почнуться, активні завершаться.

Що далі