Ringostat
Вхід

Веб-дзвінки: свій інтерфейс через SDK

~12 хв · Для розробників: готовий віджет, своя кнопка й анімація поверх SDK або повністю через ваш сервер. SPA, встановлення, вимоги.
Що отримаєте:
розмова з агентом кампанії на вашому сайті з тим інтерфейсом, який вам потрібен: від одного рядка коду до власної кнопки, анімації та видачі токенів вашим сервером.
Що потрібно заздалегідь:
кампанія з увімкненими веб-дзвінками і доданими дозволеними сайтами (див. «Веб-дзвінки: розмова з агентом на сайті»), ключ віджета або ключ «Лише веб-дзвінки», доступ до коду сайту.

Скрипт https://ai.ringostat.com/webcall/v1.js — це і готовий віджет, і SDK для власного інтерфейсу. Оберіть рівень за тим, скільки інтерфейсу ви хочете робити самі:

А. Готовий віджетНічого: кнопку, панель і підписи малює скрипт, вигляд — з конструктора в кабінеті.Ключ віджета (публічний).
Б. Свій інтерфейсКнопку, стани, анімацію і підписи; дзвінок веде SDK.Ключ віджета (публічний).
В. Свій серверТе саме, що в Б, плюс ваш сервер вирішує, кому дати розмову.Ключ «Лише веб-дзвінки» — лише на сервері.

1. Рівень А: готовий віджет із конструктора

  1. 1
    Редактор кампанії → блок «Веб-дзвінки» → «Підключення» → вкладка «Віджет» → «Відкрити конструктор».
  2. 2
    Оберіть «Як показати»: «Плаваюча кнопка» (у кутку екрана), «Блок на сторінці» (усередині <div id="ringostat-call">) або «Своя кнопка» (рівень Б, код уже з кнопкою).
  3. 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-styleorb — кнопка зі сферою (за замовчуванням), pill — проста кнопка, aura — живий шар, як на лендингу (довантажує v1-aura.js з того самого місця, що й v1.js).
data-sizes, 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).

Невідоме значення замінюється стандартним, прозорість кольору відкидається. Жоден атрибут не ховає підписи про ШІ та запис.

Мова. Якщо на сайті вже стоїть старий рядок з атрибутом data-lang, він перекриває мову з конструктора. Змінили мову в конструкторі — один раз замініть старий рядок новим, інакше мова не зміниться.
Той самий ключ двічі як плаваюча кнопка (рядок і в темі, і в GTM) дає один віджет, а в консолі — попередження «duplicate snippet ignored». Блоків на сторінці (data-container) може бути кілька.

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) + "%";
});
Підписи «Ви розмовляєте з ШІ-агентом, а не з людиною» і «Розмова записується» з посиланням на політику конфіденційності обов'язкові (EU AI Act, ст. 50) і мають бути видні біля кнопки до початку розмови. У своєму інтерфейсі за них відповідаєте ви: не ховайте їх, не робте дрібнішими за 12 px і не прибирайте зі сторінок, де є кнопка.

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: віджет сам знаходить свій рядок. Кнопка з'являється трохи пізніше, ніж із коду в шаблоні.
WixSettings → Custom Code → + Add Custom Code → вставте код, All pages, Place Code in: Body - end. Потрібен підключений домен.
ShopifyOnline 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.

Що далі