Add to Website

Как добавить

Добавьте голосового агента на любой сайт через диалог Configure Widget в настройках агента. Шаг 1: Откройте настройки агента, нажав gear icon в правом верхнем углу редактора агента. Открытие настроек агента

Шаг 2: Прокрутите до раздела Add to Website и нажмите Configure Widget. Переход к Add to Website

Шаг 3: Включите embedding, добавьте domain вашего сайта в Allowed Domains, выберите Floating Widget, Inline Component или Headless (Bring Your Own UI), при необходимости настройте кнопку (position, color, text) и нажмите Save Configurations. Сохранение конфигурации

Шаг 4: Скопируйте сгенерированный embed code и вставьте его на страницу сайта, чтобы протестировать агента. Копирование deployment code

Embed modes

Mode	Что рендерится	Когда использовать
Floating Widget	Pill-shaped CTA button, закрепленная в углу страницы.	Нужен готовый chat-bubble experience, который не нарушает текущий layout.
Inline Component	Panel внутри `<div id="agentika-inline-container">`, который вы размещаете на странице.	Нужно встроить агента в конкретный раздел: landing hero, support tab и т. д.
Headless	Без UI. Только audio pipeline и JavaScript API на `window.AgentikaWidget`.	Нужен полный контроль над UI: свои buttons, design system, framework state и animations.

Требования

Они относятся ко всем трем режимам:

Отдавайте страницу по HTTPS или с http://localhost. Браузеры запрещают доступ к microphone на обычных HTTP origins и file://.
Если вы задали Allowed Domains в dashboard, добавьте test origin, например localhost; иначе widget config и signaling requests будут отклонены. Оставьте список пустым, чтобы разрешить все domains.
Embed snippet из dashboard — это один тег <script>, который загружает agentika-widget.js асинхронно. Widget auto-initializes после загрузки и предоставляет window.AgentikaWidget. Код, который регистрирует callbacks, должен дождаться доступности widget.

Старые имена по-прежнему работают. Страницы, встроенные до переименования, продолжают работать без изменений: /embed/agentika-widget.js загружает актуальный виджет, window.AgentikaWidget — алиас window.AgentikaWidget, а <div id="agentika-inline-container"> по-прежнему подхватывается в режиме Inline. Для новых встраиваний используйте актуальные имена.

Floating widget shown in the corner of a host page

Рендерит pill-shaped button (microphone icon + text), закрепленную в углу страницы. Клик запускает звонок, повторный клик завершает его. Кнопка автоматически обновляет label и color по lifecycle звонка: configured text → “Connecting…” → “End Call” → “Retry” при ошибке. Настройте Button Text, Button Color и Position (top/bottom + left/right) из dashboard. Host page не пишет JavaScript: вся integration — это вставка embed snippet. Если нужно подписаться на lifecycle events, например для analytics, см. Lifecycle callbacks ниже.

Inline Component

Inline widget rendered inside a page section

Рендерит panel (status icon + status text + CTA button) внутри <div>, который вы размещаете на странице. Status changes обновляют panel на месте. Настройте Button Text, Button Color и Call to Action Text из dashboard.

Plain HTML

Поместите container <div> туда, где должен рендериться widget. Widget автоматически привяжется к нему.

<!-- Paste the Agentika embed snippet from the dashboard somewhere on the page -->
<div id="agentika-inline-container"></div>

React

Поскольку React монтируется после того, как widget script уже мог загрузиться, интегрируйте через initInline при первом mount и refresh при remount. Poll для window.AgentikaWidget нужен, чтобы обработать async загрузку script.

import { useEffect } from 'react';

declare global {
  interface Window {
    AgentikaWidget?: {
      initInline: (options: { container: HTMLElement }) => void;
      refresh: () => void;
      getState: () => { isInitialized: boolean };
    };
  }
}

export function Assistant() {
  useEffect(() => {
    let retries = 0;
    const tryInit = () => {
      const container = document.getElementById('agentika-inline-container');
      if (window.AgentikaWidget && container) {
        const { isInitialized } = window.AgentikaWidget.getState();
        if (isInitialized) window.AgentikaWidget.refresh();
        else window.AgentikaWidget.initInline({ container });
      } else if (retries++ < 50) {
        setTimeout(tryInit, 100);
      }
    };
    tryInit();
  }, []);

  return <div id="agentika-inline-container" />;
}

Headless Mode

В Headless mode widget не добавляет свой UI. Вы рендерите любые buttons, banners или in-call indicators и вызываете JavaScript API для запуска и завершения звонков.

JavaScript API

Method / Callback	Description
`window.AgentikaWidget.start()`	Начинает voice call. Должен вызываться внутри user-gesture handler, например `click`, чтобы браузер разрешил microphone access.
`window.AgentikaWidget.end()`	Завершает активный звонок. (`stop()` — та же функция.)
`window.AgentikaWidget.onCallStart(cb)`	Срабатывает при вызове `start()` (status `connecting`). Без payload.
`window.AgentikaWidget.onCallConnected(cb)`	Срабатывает, когда WebRTC connection установлен. Payload: `{ agentId, workflowRunId, token }`.
`window.AgentikaWidget.onCallDisconnected(cb)`	Срабатывает только если звонок был connected, когда выполняется teardown. Payload: `{ agentId, workflowRunId, token, durationSeconds }`.
`window.AgentikaWidget.onCallEnd(cb)`	Срабатывает при teardown call session, включая failed-to-connect attempts. Без payload.
`window.AgentikaWidget.onStatusChange(cb)`	Срабатывает при каждом status change. Callback получает `(status, text, subtext)`. Status values: `idle`, `connecting`, `connected`, `failed`.
`window.AgentikaWidget.onError(cb)`	Срабатывает при errors: mic permission denied, server error и т. д. Callback получает `Error` object.

Все on* setters — single-listener: повторный вызов того же setter заменяет предыдущий handler.

О timing. Widget script загружается асинхронно, поэтому window.AgentikaWidget может еще не существовать, когда ваш inline <script> впервые выполняется. Примеры ниже предполагают, что window.AgentikaWidget уже доступен при регистрации. Чтобы гарантировать это:

Vanilla JS: оберните registration code в window.addEventListener('load', () => { /* register here */ }).
React: внутри useEffect регистрируйтесь сразу, если document.readyState === 'complete'; иначе добавьте одноразовый window.load listener, который выполнит регистрацию.
Click handlers, вызывающие start() / end(), не требуют guard: к моменту клика widget уже обычно загружен.

Vanilla JS

<button id="talk-btn">Talk to AI</button>

<script>
  let callStatus = 'idle';
  const btn = document.getElementById('talk-btn');

  function render() {
    btn.textContent =
      callStatus === 'connected' ? 'End Call'
      : callStatus === 'connecting' ? 'Connecting…'
      : callStatus === 'failed' ? 'Retry'
      : 'Talk to AI';
  }

  window.AgentikaWidget.onStatusChange((status) => {
    callStatus = status;
    render();
  });

  window.AgentikaWidget.onError((err) => {
    console.error('Agentika error:', err.message);
  });

  btn.addEventListener('click', () => {
    if (callStatus === 'connected' || callStatus === 'connecting') {
      window.AgentikaWidget.end();
    } else {
      window.AgentikaWidget.start();
    }
  });
</script>

React + TypeScript

import { useEffect, useState } from 'react';

type CallStatus = 'idle' | 'connecting' | 'connected' | 'failed';

declare global {
  interface Window {
    AgentikaWidget: {
      start: () => void;
      end: () => void;
      onStatusChange: (cb: (status: CallStatus, text?: string, subtext?: string) => void) => void;
      onError: (cb: (err: Error) => void) => void;
    };
  }
}

export function TalkButton() {
  const [status, setStatus] = useState<CallStatus>('idle');

  useEffect(() => {
    window.AgentikaWidget.onStatusChange((s) => setStatus(s));
    window.AgentikaWidget.onError((err) => console.error('Agentika error:', err.message));
  }, []);

  const isLive = status === 'connected' || status === 'connecting';
  const label = { idle: 'Talk to AI', connecting: 'Connecting…', connected: 'End Call', failed: 'Retry' }[status];

  return (
    <button onClick={() => (isLive ? window.AgentikaWidget.end() : window.AgentikaWidget.start())}>
      {label}
    </button>
  );
}

start() должен запускаться внутри реального user-gesture handler (click, touchend и т. д.). Браузеры не дают microphone access скриптам, которые запрашивают его вне такого handler: вызов start() из setTimeout или при загрузке страницы завершится permission error.

Lifecycle callbacks (all modes)

Callbacks on* из Headless JavaScript API работают во всех трех embed modes, не только в Headless. Используйте их для analytics или запуска UI на host page даже когда widget рендерит собственный UI (Floating или Inline).

window.AgentikaWidget.onCallConnected(({ agentId, workflowRunId }) => {
  analytics.track('voice_call_started', { agentId, workflowRunId });
});

window.AgentikaWidget.onCallDisconnected(({ workflowRunId, durationSeconds }) => {
  analytics.track('voice_call_ended', { workflowRunId, durationSeconds });
});

onCallConnected и onCallDisconnected срабатывают только когда звонок действительно установил media connection. Failed-to-connect attempts, например отказ microphone или network failure, их не вызывают, поэтому analytics остаются чистыми.

Начало работы

Основные понятия

Конфигурации

Конструктор голосовых агентов

Телефония

Интеграции

Как добавить

Embed modes

Требования

Floating Widget

Inline Component

Plain HTML

React

Headless Mode

JavaScript API

Vanilla JS

React + TypeScript

Lifecycle callbacks (all modes)

​Как добавить

​Embed modes

​Требования

​Floating Widget

​Inline Component

​Plain HTML

​React

​Headless Mode

​JavaScript API

​Vanilla JS

​React + TypeScript

​Lifecycle callbacks (all modes)

Как добавить

Embed modes

Требования

Floating Widget

Inline Component

Plain HTML

React

Headless Mode

JavaScript API

Vanilla JS

React + TypeScript

Lifecycle callbacks (all modes)