Веб-дзвінки: свій інтерфейс через SDK
- Що отримаєте:
- розмова з агентом кампанії на вашому сайті з тим інтерфейсом, який вам потрібен: від одного рядка коду до власної кнопки, анімації та видачі токенів вашим сервером.
- Що потрібно заздалегідь:
- кампанія з увімкненими веб-дзвінками і доданими дозволеними сайтами (див. «Веб-дзвінки: розмова з агентом на сайті»), ключ віджета або ключ «Лише веб-дзвінки», доступ до коду сайту.
Скрипт https://ai.ringostat.com/webcall/v1.js — це і готовий віджет, і SDK для власного інтерфейсу. Оберіть рівень за тим, скільки інтерфейсу ви хочете робити самі:
| Рівень | Що малюєте ви | Ключ |
|---|---|---|
| А. Готовий віджет | Нічого: кнопку, панель і підписи малює скрипт, вигляд — з конструктора в кабінеті. | Ключ віджета (публічний). |
| Б. Свій інтерфейс | Кнопку, стани, анімацію і підписи; дзвінок веде SDK. | Ключ віджета (публічний). |
| В. Свій сервер | Те саме, що в Б, плюс ваш сервер вирішує, кому дати розмову. | Ключ «Лише веб-дзвінки» — лише на сервері. |
1. Рівень А: готовий віджет із конструктора
- 1Редактор кампанії → блок «Веб-дзвінки» → «Підключення» → вкладка «Віджет» → «Відкрити конструктор».
- 2Оберіть «Як показати»: «Плаваюча кнопка» (у кутку екрана), «Блок на сторінці» (усередині <div id="ringostat-call">) або «Своя кнопка» (рівень Б, код уже з кнопкою).
- 3Налаштуйте стиль, колір, текст кнопки, ім'я агента, мову й відступи, збережіть і скопіюйте код. У data-privacy-url вкажіть свою політику конфіденційності.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<КЛЮЧ_ВІДЖЕТА>"
data-privacy-url="https://example.com/privacy" async></script>Вигляд зберігається в кабінеті: віджет читає його під час завантаження (GET /web-call/widget-config, чекає не довше 1,5 секунди і пам'ятає 5 хвилин у межах вкладки). Тому після змін у конструкторі код на сайті міняти не треба — лише якщо змінився режим «Як показати». Якщо налаштування не завантажились, кнопка з'являється у стандартному вигляді.
Будь-який data-атрибут у рядку перекриває збережене в кабінеті. Окрім атрибутів із базового гайда (data-lang, data-position, data-color, data-container), вигляд задають:
| Атрибут | Значення |
|---|---|
| data-style | orb — кнопка зі сферою (за замовчуванням), pill — проста кнопка, aura — живий шар, як на лендингу (довантажує v1-aura.js з того самого місця, що й v1.js). |
| data-size | s, m або l. |
| data-label | Текст кнопки, до 40 символів. Без нього — стандартний текст мовою віджета. |
| data-title | Ім'я агента в панелі дзвінка, до 60 символів. |
| data-palette | Для aura: default, dental, auto, realestate, shop або чотири кольори через кому "#темний,#основний,#м'ятний,#блакитний". Без нього — з data-color. |
| data-motion | Для aura: calm, normal або lively. |
| data-offset-x, data-offset-y | Відступ плаваючої кнопки від бічного краю й від низу, 0–200 px (за замовчуванням 16). |
Невідоме значення замінюється стандартним, прозорість кольору відкидається. Жоден атрибут не ховає підписи про ШІ та запис.
2. Рівень Б: свій інтерфейс через SDK
З data-auto="false" скрипт нічого не малює і дає window.RingostatWebCall. Дзвінок (мікрофон, токен, звук, перебивання) веде SDK, а кнопку, стани й анімацію робите ви. Режим «Своя кнопка» в конструкторі генерує саме такий код; нижче — з чого він складається.
| Виклик | Що робить |
|---|---|
| RingostatWebCall.create({ key }) | Новий об'єкт розмови. Один об'єкт — одна розмова: для наступної створіть новий. |
| call.start() | Просить мікрофон, отримує токен і підключається. Лише всередині обробника натискання, до будь-якого await. Promise; при помилці відхиляється з err.code. |
| call.stop() | Завершує розмову з боку відвідувача. |
| call.setMuted(true | false) | Вимикає й вмикає мікрофон; агенту йде тиша, розмова не обривається. |
| call.on(подія, fn) | Підписка на подію; повертає функцію, яка відписує. |
| Подія | Значення |
|---|---|
| state | { status, agentSpeaking, userSpeaking }; status: idle → connecting → live → ended. |
| transcript | { role: "agent" | "user", text, final, id }: субтитри. Поки final: false, фраза ще уточнюється — замінюйте її текст за id, а не дописуйте. |
| level | Гучність мікрофона відвідувача, 0..1, близько 20 разів на секунду (0, коли мікрофон вимкнено). |
| outputLevel | Гучність голосу агента, 0..1, близько 30 разів на секунду; 0 наприкінці. |
| end | { reason, code? }, рівно один раз. reason: user_ended — stop(); failed — розмова не почалась; error — помилка сервера; disconnected — обрив зв'язку (без code); інше — розмову завершив сервер (агент попрощався, вичерпано тривалість). code є, коли reason — failed або error. |
Помилки: що показати відвідувачу
Код приходить у події end (e.code) і в err.code, якщо start() відхилився. Зручно показувати повідомлення в одному місці — в end, а start().catch() лише гасить відхилення.
| Код | Що показати відвідувачу |
|---|---|
| mic_denied | «Дозвольте доступ до мікрофона, щоб поговорити з агентом» і як це зробити: значок замка чи мікрофона в адресному рядку → дозволити → «Ще раз». |
| mic_not_found | «Мікрофон не знайдено»: підключіть його або закрийте програму, яка його використовує. |
| mic_unsupported | «Мікрофон недоступний у цьому браузері: відкрийте сторінку в Safari або Chrome». Буває у вбудованих браузерах Instagram, Telegram, Facebook і в старих браузерах. |
| busy | «Агент зараз зайнятий, спробуйте за хвилину». У err.retryAfter — через скільки секунд. |
| rate_limited, daily_limit | «Забагато спроб, спробуйте трохи пізніше». |
| origin_not_allowed, web_calls_disabled, insufficient_funds | Відвідувачу — «Розмова зараз недоступна». Це налаштування кабінету: сайт не в «Дозволених сайтах», веб-дзвінки вимкнені, немає коштів. |
| unavailable, timeout, connect_failed, audio_unavailable; reason disconnected | «Не вдалося з'єднатися. Спробуйте ще раз». |
Приклад: свій шар за ~20 рядків
Кнопка, коло, яке «дихає» в такт голосу агента (outputLevel), статус, вимкнення мікрофона та обов'язкові підписи з посиланням на політику. Сторінка повністю робоча: підставте ключ віджета, адресу політики й домен у «Дозволені сайти».
<div class="rwc">
<div id="orb" class="orb" aria-hidden="true"></div>
<button id="talk" type="button">Поговорити з агентом</button>
<button id="mute" type="button" hidden>Вимкнути мікрофон</button>
<p id="status" role="status" aria-live="polite"></p>
<p class="notice">Ви розмовляєте з ШІ-агентом, а не з людиною. Розмова записується.
<a href="https://example.com/privacy" target="_blank" rel="noopener">Політика конфіденційності</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="<КЛЮЧ_ВІДЖЕТА>" data-auto="false"></script>
<script>
const ERRORS = {
mic_denied: "Дозвольте доступ до мікрофона, щоб поговорити з агентом.",
mic_not_found: "Мікрофон не знайдено.",
mic_unsupported: "Мікрофон недоступний: відкрийте сторінку в Safari або Chrome.",
busy: "Агент зараз зайнятий. Спробуйте за хвилину.",
rate_limited: "Забагато спроб. Спробуйте трохи пізніше.",
daily_limit: "Забагато спроб. Спробуйте трохи пізніше.",
};
const FAIL = "Не вдалося з'єднатися. Спробуйте ще раз.";
const $ = (id) => document.getElementById(id);
let call = null, muted = false;
$("talk").onclick = () => {
if (call) return call.stop(); // друге натискання завершує
call = RingostatWebCall.create({ key: "<КЛЮЧ_ВІДЖЕТА>" });
call.on("state", (s) => {
$("status").textContent = s.status === "live" ? "Говоріть, агент слухає" : s.status === "connecting" ? "З'єднуємо…" : "";
$("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 = "Поговорити з агентом";
$("mute").textContent = "Вимкнути мікрофон";
$("status").textContent = e.code ? ERRORS[e.code] || FAIL
: e.reason === "disconnected" ? FAIL : "Дякуємо за розмову!";
});
$("talk").textContent = "Завершити";
call.start().catch(() => {}); // повідомлення покаже подія end
};
$("mute").onclick = () => {
muted = !muted;
call && call.setMuted(muted);
$("mute").textContent = muted ? "Увімкнути мікрофон" : "Вимкнути мікрофон";
};
</script>Субтитри й індикатор мікрофона: додайте розмітку поруч із кнопкою, а підписки — в обробник $("talk").onclick одразу після create() (до натискання call ще null). Обробники подій мають бути короткими й не кидати помилок: помилка в обробнику level зупиняє обробку кадру мікрофона, і агент не почує відвідувача.
<!-- розмітка: поруч із кнопкою -->
<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>
// в обробнику $("talk").onclick, одразу після 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) + "%";
});3. Рівень В: токен від вашого сервера
Коли розмову можна давати не всім (лише авторизованим клієнтам, після капчі, з вашим лімітом), токен видає ваш сервер методом webCall.create з ключем «Лише веб-дзвінки». Ключ зберігайте на сервері; на сторінку він не потрапляє ніколи. Параметри й коди помилок webCall.create — у розділі «Варіант Б: через ваш сервер» базового гайда.
У браузері той самий інтерфейс, що в рівні Б, лише замість key — getTicket: функція, яка повертає { token, wsUrl } від вашого сервера. SDK спершу просить мікрофон, потім викликає getTicket (токен живе 20 секунд) і підключається.
<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
// замість RingostatWebCall.create({ key }) з прикладу вище:
call = RingostatWebCall.create({
getTicket: (signal) =>
fetch("/api/web-call-token", { method: "POST", signal }).then((r) => r.json()),
});
</script>// Сервер (Node.js 18+, Express): POST /api/web-call-token
app.post("/api/web-call-token", async (req, res) => {
// 1. Перевірте відвідувача: ваша сесія, капча, ліміт.
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 } }), // публічна IP відвідувача
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 }); // лише це, без ключа
} catch {
res.status(503).json({ code: "unavailable" }); // Ringostat недоступний, не відповів за 10 с або відповів не JSON
}
});Якщо getTicket відхилився або повернув не { token, wsUrl } з адресою wss://, розмова завершується з кодом unavailable. Причину відмови (busy, rate_limited) ваш endpoint може повернути у своїй відповіді, а сторінка — показати свій текст. За проксі clientIp беріть із заголовка, якому довіряєте (X-Forwarded-For від вашого балансувальника).
4. SPA: React, Next.js, Vue
- Підключайте скрипт один раз на весь застосунок (index.html, кореневий layout), а не в компоненті сторінки.
- Якщо роутер перемальовує body або контейнер, віджет повертається сам. data-container може з'явитися на сторінці до 10 секунд пізніше за скрипт.
- RingostatWebCall.unmount() завершує розмову, прибирає віджети й перестає за ними стежити. RingostatWebCall.mount(options?) показує віджет знову; options — ті самі параметри, що й data-атрибути, у camelCase без data-: { container: "#talk", offsetX: "24" }. Поки віджет показано, mount() повертає наявний, тому щоб перенести його в інший контейнер, спершу unmount().
- v1.js вантажиться асинхронно, тож ефект сторінки чи перший маршрут можуть спрацювати раніше за нього. Тому в SPA ставте data-auto="false" і показуйте віджет функцією webCallFor нижче: вона чекає SDK і застосовує те, що потрібно поточному маршруту, без «спалаху» віджета там, де його не має бути. mount() повертає Promise з елементом віджета або null (причина — у попередженні [Ringostat] в консолі).
// webCallRoute.js — один модуль на весь застосунок.
// next: false — без віджета; undefined — плаваюча кнопка; { container: "#talk" } — у блоці.
let want, shown, timer, seq = 0;
export async function webCallFor(next) {
want = next;
const w = window.RingostatWebCall;
if (!w || !w.mount) { // v1.js ще вантажиться: застосуємо, щойно завантажиться
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; // той самий режим: віджет і розмова лишаються
const my = ++seq; // кожен виклик — свій номер: відповідь застарілого виклику ігнорується
shown = key;
w.unmount();
if (want === false) return;
let host = null;
try { host = await w.mount(want); } catch {}
if (!host && my === seq) shown = undefined; // не показано (напр. контейнера не було 10 с): наступний виклик спробує знову
}// Next.js, app/layout.tsx: скрипт один раз; з data-auto="false" віджет показує webCallFor
import Script from "next/script";
<Script src="https://ai.ringostat.com/webcall/v1.js" strategy="afterInteractive"
data-key="<КЛЮЧ_ВІДЖЕТА>" data-privacy-url="/privacy" data-auto="false" />
// Next.js: клієнтський компонент у кореневому layout вирішує за адресою
"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: спрацьовує і для першого маршруту
router.afterEach((to) => webCallFor(to.meta.webCall)); // meta: { webCall: false } або { webCall: { container: "#talk" } }Для рівня Б у SPA створюйте об'єкт розмови в обробнику натискання, як у прикладі, і викликайте call.stop() при виході зі сторінки (у cleanup ефекту чи onBeforeUnmount), щоб розмова не тривала без інтерфейсу.
5. Встановлення на сайт
| Де | Як |
|---|---|
| Свій сайт | Вставте код перед </body> на всіх сторінках, де потрібна кнопка (у спільному шаблоні). |
| Tilda | Налаштування сайту → Ще → HTML-код для вставки всередину body → вставте код → збережіть і опублікуйте всі сторінки. Для «Блок на сторінці» додайте <div id="ringostat-call"></div> блоком «HTML-код» (T123) у потрібне місце. |
| WordPress | Плагін для коду в header/footer (напр. WPCode) → Footer → вставте код і збережіть. Або footer.php дочірньої теми перед </body>. |
| Google Tag Manager | Новий тег «Custom HTML» → вставте код без змін → тригер All Pages → Submit і Publish. Працює, хоча GTM запускає скрипт без document.currentScript: віджет сам знаходить свій рядок. Кнопка з'являється трохи пізніше, ніж із коду в шаблоні. |
| Wix | Settings → Custom Code → + Add Custom Code → вставте код, All pages, Place Code in: Body - end. Потрібен підключений домен. |
| Shopify | Online Store → Themes → … → Edit code → layout/theme.liquid → вставте код перед </body> → Save. |
Додайте в «Дозволені сайти» кожен домен, де стоїть код, включно з www і тестовими адресами конструктора (напр. project123.tilda.ws): збіг точний.
6. Вимоги й обмеження
- HTTPS. Браузер дає мікрофон лише захищеним сторінкам; для розробки підходить http://localhost.
- Дозвіл на мікрофон. Перший старт показує запит браузера. У iframe потрібен allow="microphone": <iframe src="…" allow="microphone">; Origin запиту тоді — домен сторінки в iframe, його й додайте в «Дозволені сайти».
- Вбудовані браузери (Instagram, Telegram, Facebook) часто не дають мікрофон: start() завершується з mic_unsupported. Готовий віджет на сторінках без мікрофона (без HTTPS, без navigator.mediaDevices, iframe без allow) не з'являється; у своєму інтерфейсі сховайте кнопку, якщо !window.isSecureContext || !navigator.mediaDevices?.getUserMedia.
- Content-Security-Policy — як у базовому гайді (script-src https://ai.ringostat.com, connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com). Для рівня В додайте в connect-src адресу свого endpoint (зазвичай 'self'). Якщо CSP з nonce, поставте nonce на тег v1.js: v1-aura.js отримає той самий.
- Дозволені сайти: токен видається лише сторінкам доменів зі списку кампанії, збіг точний.
- Старт лише в кліку: call.start() — у обробнику натискання, не під час завантаження сторінки й не після таймера чи довгого await. Інакше браузер не дасть мікрофон і звук.
- Одна плаваюча кнопка на ключ на сторінці; дублікат ігнорується з попередженням у консолі.
- Обов'язкові підписи про ШІ та запис з посиланням на політику конфіденційності не вимикаються жодним налаштуванням; у своєму інтерфейсі їх показуєте ви.
- Тривалість розмови, одночасні дзвінки й ліміт розмов з однієї IP-адреси — з налаштувань кампанії та проєкту.
- Не копіюйте v1.js на свій сервер: підключений з ai.ringostat.com, він оновлюється сам. Копія має віддаватися з Content-Type: application/javascript; charset=UTF-8 і з v1-aura.js поруч, інакше зламаються тексти або стиль aura.
Що далі
- Веб-дзвінки: розмова з агентом на сайті — увімкнення, ключі, webCall.create, CSP і коди помилок.
- Методи /rpc з прикладами — webCall.create серед інших методів.
- Вебхуки: результати дзвінків — підсумок веб-дзвінка у вашу CRM.