> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Звонок с сайта: Web SDK

> `POST /v1/calls/web`, браузерный SDK `@hubtalk-ai/web-sdk` и готовый виджет: разговор с агентом прямо на вашем сайте.

# Звонок с сайта: Web SDK

Посетитель вашего сайта нажимает кнопку и говорит с агентом из браузера — без телефонной линии, по микрофону. Для этого есть эндпоинт `POST /v1/calls/web` и браузерный SDK [`@hubtalk-ai/web-sdk`](https://www.npmjs.com/package/@hubtalk-ai/web-sdk), а в SDK — готовый виджет: кнопка в углу страницы и панель звонка.

Если нужно просто дать человеку поговорить с агентом, ничего не встраивая, хватит [демо-ссылки](https://docs.hubtalk.ai/ru/v4/platform/demo-links.md). Web SDK — для случая, когда звонок начинается на вашем сайте, на вашем домене и с переменными, которые знает ваша система.

## Как это устроено

1. Посетитель нажимает кнопку звонка на вашей странице.
2. Страница просит **ваш сервер** начать звонок. Сервер вызывает `POST /v1/calls/web` с [API-ключом](https://docs.hubtalk.ai/ru/v4/web-api/start.md) организации и получает сессию: `access_token` и `url`.
3. Сервер отдаёт сессию странице, страница передаёт её в SDK. Дальше разговор идёт напрямую между браузером и платформой, а состояние звонка приходит в страницу событиями.

> [!WARNING]
>
> **API-ключ не попадает в браузер.** Его знает только ваш сервер. Странице достаётся одноразовая сессия на один звонок — она даёт войти только в этот разговор и больше ничего.

## Что нужно заранее

* **Агент опубликован.** Звонит опубликованная версия; черновик не подключится. Привязка к телефонии для web-звонка не нужна.
* **Выпущен API-ключ** — раздел **«API-ключи»**, см. [Ключ доступа](https://docs.hubtalk.ai/ru/v4/web-api/start.md). Ключ хранится на вашем сервере.
* **Страница открыта по HTTPS.** Без защищённого соединения браузер не даст доступ к микрофону. Исключение — `localhost` при разработке.

## `POST /v1/calls/web`

Создаёт web-звонок и выдаёт сессию для браузера. Запрос делает ваш сервер, с заголовком `Authorization: Bearer <API-ключ>`.

| Поле | Тип | Обяз. | По умолч. | Описание |
| - | - | - | - | - |
| `agent_id` | string | да | — | Имя агента. Должен быть **опубликован**. |
| `dynamic_variables` | object | нет | `{}` | Переменные сценария — те же `{{var}}`, что в узлах: имя клиента, номер заказа. |
| `metadata` | object | нет | `{}` | Ваша непрозрачная нагрузка для сопоставления. Возвращается без изменений в объекте звонка и в каждом [вебхуке](https://docs.hubtalk.ai/ru/v4/web-api/webhooks.md). |
| `avatar` | boolean | нет | `false` | Попросить живой аватар для этого звонка, см. [Живой аватар](#живой-аватар). Только `true` или `false`: строка или число — `422`. |
| `avatar_quality` | string | нет | настройка агента | Качество видео аватара: `low`, `medium`, `high`, `very_high`. Неизвестное значение не ломает звонок: платформа его пропускает и берёт качество из настройки агента. |

```bash theme={null}
curl -X POST "$BASE_URL/v1/calls/web" \
  -H "Authorization: Bearer $HUBTALK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a90-site-call-1" \
  -d '{
    "agent_id": "clinic_booking",
    "dynamic_variables": {"client_name": "Айгерим"},
    "metadata": {"lead_id": "L-1042"}
  }'
```

**Ответ — `201 Created`**: [объект звонка](https://docs.hubtalk.ai/ru/v4/web-api/calls.md#объект-звонка) и три поля сессии.

| Поле | Описание |
| - | - |
| `access_token` | Токен для браузера. Живёт **2 часа** и не продлевается. |
| `url` | Адрес, к которому подключается браузер. |
| `room` | Комната звонка; совпадает с `call_id`. |
| `call_id` | Идентификатор звонка вида `web-<uuid>`. По нему звонок читается через `GET /v1/calls/{call_id}` и находится в вебхуках. |

Ответ целиком можно отдать странице и передать в SDK как есть: лишние поля SDK пропускает.

**Ошибки**

| Статус | `error.code` | Условие |
| - | - | - |
| 404 | `agent_not_found` | агента с таким именем нет в вашей организации |
| 409 | `agent_not_published` | у агента нет опубликованной версии |
| 422 | `invalid_request` | тело не проходит проверку схемы; детали по полям — в `message` |
| 429 | `org_concurrency_limit` | достигнут лимит одновременных звонков организации |
| 503 | `agent_dispatch_failed` | платформе сейчас некуда подключить агента — повторите позже |

Общие ошибки ключа и лимита запросов — в [«Ошибках»](https://docs.hubtalk.ai/ru/v4/web-api/errors.md).

**Повтор запроса.** Заголовок `Idempotency-Key` защищает от двойного звонка при ретраях: повтор с тем же ключом в течение суток вернёт ту же сессию, второго звонка не будет. Ключ повтора — на один звонок: для следующего посетителя нужен новый.

**Сессия — на один звонок.** Токен живёт 2 часа и не продлевается, поэтому выдавайте новую сессию на каждый звонок, а не держите одну на открытой странице.

### Звонок в Истории и вебхуках

Web-звонок сразу появляется в [Истории](https://docs.hubtalk.ai/ru/v4/platform/campaign-history) как активный разговор канала **«Web-звонок»** (`channel: "web"`, `direction: "web"`). Транскрипт, запись, пост-аналитика и [вебхуки](https://docs.hubtalk.ai/ru/v4/web-api/webhooks.md) работают как у телефонного звонка. В сценарии переменная `{{direction}}` равна `web` — по ней агент может говорить с посетителем сайта иначе, чем по телефону.

Жизненный цикл короче телефонного: `queued` → `ongoing` → `ended`, без `ringing` и `failed`. Поля номеров и транка у web-звонка пустые, `answered_at` — `null`.

## Установка SDK

```bash theme={null}
npm install @hubtalk-ai/web-sdk
```

```ts theme={null}
import { VoiceClient } from '@hubtalk-ai/web-sdk';
```

**Без сборщика.** В пакете, в папке `dist`, лежат готовые файлы для подключения обычным тегом `<script>`: `voice-client.bundle.js` — клиент, `widget.bundle.js` и `widget.css` — [виджет](#готовый-виджет). Положите их на свой сервер:

```html theme={null}
<script src="/sdk/voice-client.bundle.js"></script>
<script>
  const client = new VoiceClient();
</script>
```

Сторонний CDN не нужен: всё, что требуется SDK, внутри этих файлов.

## Первый звонок

На сервере — эндпоинт, который вызывает `POST /v1/calls/web` и возвращает ответ странице. Пример на Node.js (Express):

```js theme={null}
app.post('/api/start-voice-call', async (req, res) => {
  const r = await fetch(`${process.env.HUBTALK_BASE_URL}/v1/calls/web`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.HUBTALK_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agent_id: 'clinic_booking',
      dynamic_variables: { client_name: req.user?.name ?? '' },
    }),
  });
  res.status(r.status).json(await r.json());
});
```

Переменные звонка задаёт сервер. Если какое-то значение приходит со страницы, принимайте только те поля, которые вы сами ожидаете, — так посетитель не подставит в сценарий чужие данные.

На странице:

```ts theme={null}
const client = new VoiceClient();

startButton.addEventListener('click', async () => {
  const session = await fetch('/api/start-voice-call', { method: 'POST' }).then((r) => r.json());
  await client.startCall(session);
});

client.on('transcript', ({ role, text, final, id }) => renderBubble(id, role, text, final));
client.on('callEnded', ({ reason }) => console.log('звонок завершён:', reason));

endButton.addEventListener('click', () => client.stopCall());
```

> [!NOTE]
>
> **`startCall` вызывайте внутри обработчика нажатия.** Браузер разрешает звук агента и доступ к микрофону только после действия пользователя. В Safari на iPhone сетевой запрос между нажатием и `startCall()` может «съесть» это действие — тогда запрашивайте сессию заранее, например при открытии панели звонка.

## VoiceClient

### Параметры

`new VoiceClient(options?)` — все параметры необязательны.

| Параметр | По умолчанию | Описание |
| - | - | - |
| `audioContainer` | скрытый `<div>`, который создаёт SDK | Куда SDK кладёт `<audio>` с голосом агента. |
| `logger` | `console` | Свой приёмник логов `{ error, debug }`. Токены в логах маскируются в любом случае. |
| `logLevel` | `'error'` | `'silent'`, `'error'` или `'debug'`. |
| `connectTimeoutMs` | 15 секунд | Сколько ждать подключения. |

### Методы

| Метод | Что делает |
| - | - |
| `startCall(session, options?)` | Подключается и включает микрофон. Принимает ответ `POST /v1/calls/web` как есть или `{ accessToken, url }`. Второй вызов во время звонка — ошибка `ALREADY_IN_CALL`. `{ audio: false }` — [текстовый звонок](#текстовый-звонок). |
| `stopCall()` | Завершает звонок. Если звонка нет — ничего не делает, без ошибки. |
| `sendText(text)` | Отправляет агенту текст от посетителя: агент прерывает свою речь и отвечает, как на сказанное голосом. Вне звонка — `NOT_IN_CALL`; текст длиннее 1000 символов обрезается. В чат сообщение само не добавляется — оно вернётся событием `transcript` с `role: 'user'`. |
| `setMicrophoneEnabled(enabled)` | Выключает и включает микрофон во время голосового звонка; звонок при этом не прерывается. `isMicrophoneEnabled()` — текущее состояние. |
| `resumeAudio()` | Включает звук агента, если браузер его заблокировал (событие `audioPlaybackBlocked`). Вызывайте по нажатию кнопки «Включить звук». |
| `getState()` | Состояние соединения: `idle`, `connecting`, `connected`, `reconnecting`, `disconnected`, `error`. |
| `getAgentState()` | Что делает агент: `unknown`, `initializing`, `listening`, `thinking`, `speaking`. |
| `getCallId()` | `call_id` звонка — тот же, что принимает `GET /v1/calls/{call_id}`; до подключения — `null`. |
| `on` / `off` / `once` | Подписаться на событие, отписаться, подписаться один раз. |
| `destroy()` | Завершает звонок и освобождает всё; после этого клиент не используется. |

### События

| Событие | Данные |
| - | - |
| `callStarted` | `{ callId }` |
| `callEnded` | `{ callId, reason }`. `reason`: `local` — завершили вы (`stopCall`), `remote` — завершил агент, `connection_lost` — пропала связь, `error` — сбой. |
| `connectionStateChanged` | `{ state, previous }` |
| `agentStateChanged` | `{ state, previous }` |
| `agentSpeakingStarted` / `agentSpeakingStopped` | `{}` |
| `transcript` | `{ role, text, final, id }` — реплика разговора, `role`: `user` или `agent`. Пока `final: false`, реплика ещё дописывается: рисуйте один пузырь на каждый `id` и обновляйте его. |
| `microphoneStateChanged` | `{ enabled }` — микрофон включён или выключен. |
| `audioPlaybackBlocked` | `{}` — браузер заблокировал звук агента. Звонок продолжается; покажите кнопку, которая вызовет `resumeAudio()`. |
| `error` | `VoiceError` — см. ниже. |

### Текстовый звонок

`startCall(session, { audio: false })` начинает тот же звонок без микрофона и звука: браузер не спрашивает разрешений, разговор идёт текстом через `sendText()` и события `transcript`. Это режим для посетителя, который не может или не хочет говорить вслух. Ответы агента приходят в темпе речи.

### Ошибки SDK

Любой сбой — объект `VoiceError`: `{ code, message, state, cause? }`. Решения принимайте по `code`; `message` — строка для логов, текст для посетителя пишете вы.

| Код | Когда |
| - | - |
| `INVALID_PARAMS` | в сессии нет `access_token` или `url` |
| `WEBRTC_UNSUPPORTED` | браузер не поддерживает звонки или страница открыта не по HTTPS |
| `MICROPHONE_PERMISSION_DENIED` | посетитель запретил доступ к микрофону |
| `MICROPHONE_UNAVAILABLE` | микрофона нет или он занят |
| `AUDIO_PLAYBACK_BLOCKED` | браузер повторно заблокировал звук после `resumeAudio()` |
| `TOKEN_EXPIRED` | сессия истекла до начала звонка |
| `TOKEN_INVALID` | платформа не приняла токен сессии |
| `CONNECTION_FAILED` | не удалось подключиться |
| `CONNECTION_LOST` | связь пропала и не восстановилась |
| `ALREADY_IN_CALL` | звонок уже идёт |
| `NOT_IN_CALL` | действие вне звонка: `sendText`, переключение микрофона |
| `SERVER_ERROR` | любой другой сбой |

## Готовый виджет

Если своя вёрстка не нужна, в пакете есть виджет: кнопка в углу страницы и панель звонка с состоянием агента, таймером, кнопками микрофона и завершения, чатом и транскриптом после звонка. Тексты виджета — на английском или русском.

```ts theme={null}
import { mountWidget } from '@hubtalk-ai/web-sdk/widget';
import '@hubtalk-ai/web-sdk/widget.css';

const widget = mountWidget({
  container: document.getElementById('support'),
  locale: 'ru',
  async createSession() {
    const r = await fetch('/api/start-voice-call', { method: 'POST' });
    if (!r.ok) throw new Error('Session unavailable');
    return r.json(); // { access_token, url, … } — без API-ключа
  },
});

// при уходе со страницы или удалении компонента
widget.destroy();
```

Без сборщика — те же файлы из `dist`:

```html theme={null}
<link rel="stylesheet" href="/sdk/widget.css">
<div id="support"></div>
<script src="/sdk/widget.bundle.js"></script>
<script>
  HubTalkWidget.mountWidget({
    container: document.getElementById('support'),
    locale: 'ru',
    createSession: async () => {
      const r = await fetch('/api/start-voice-call', { method: 'POST' });
      if (!r.ok) throw new Error('Session unavailable');
      return r.json();
    },
  });
</script>
```

| Параметр | По умолчанию | Описание |
| - | - | - |
| `container` | обязателен | Элемент страницы, в котором живёт виджет. |
| `createSession` | обязателен | Функция, которая просит ваш сервер начать звонок и возвращает ответ `POST /v1/calls/web`. Виджет вызывает её при нажатии **«Начать разговор»**. |
| `locale` | `'en'` | Язык текстов виджета: `'en'` или `'ru'`. |
| `mode` | `'standard'` | `'standard'` — панель звонка и чата; `'avatar'` — панель с карточкой [живого аватара](#живой-аватар). |
| `screenAdaptation` | `{ mode: 'height' }` | Как открытая панель встаёт на экране. `'height'` — панель в углу, высотой в половину экрана. `'full-height'` — панель от шапки сайта до низа экрана; шапку виджет находит сам, или укажите её селектор в `headerSelector`. На телефонах панель занимает весь экран в любом режиме. |
| `renderCallDetails` | нет | Функция, которая один раз рисует в панели вашу форму — например, выбор темы обращения. Значения формы `createSession` читает сама. Во время звонка виджет форму прячет. |
| `avatar` | нет | Настройки карточки аватара для режима `'avatar'`, см. ниже. |

Стили виджета подключаются отдельным файлом `widget.css` и действуют только внутри виджета — оформление вашей страницы они не меняют.

### Живой аватар

В режиме `'avatar'` панель показывает **живое видео AI-аватара**: лицо, которое говорит голосом агента синхронно с речью. Видео идёт по тому же соединению, что и звук.

* **Аватар включается для агента поддержкой платформы** — она же задаёт, какое лицо будет в звонке. Напишите в поддержку, для какого агента нужен аватар, и уточните, какое лицо выбрано.
* **Ваш сервер просит аватар** полем `"avatar": true` в `POST /v1/calls/web`. Виджет подсказывает, когда это нужно: `createSession` получает `{ avatar, avatarQuality }`, и `avatar` равно `true` в режиме `'avatar'`. Это просьба, а не гарантия: если у агента аватар не включён, звонок идёт только со звуком, ответ API не меняется.
* **Заставку показываете вы.** Пока видео нет — до звонка, в первые секунды, если видео прервалось, — на месте аватара стоит ваша картинка `avatar.posterUrl` или пара беззвучных роликов. Подберите заставку, похожую на лицо аватара, иначе смена будет заметна.

```ts theme={null}
mountWidget({
  container: document.getElementById('support'),
  mode: 'avatar',
  locale: 'ru',
  async createSession({ avatar, avatarQuality }) {
    const r = await fetch('/api/start-voice-call', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ avatar, avatar_quality: avatarQuality }),
    });
    if (!r.ok) throw new Error('Session unavailable');
    return r.json();
  },
  avatar: {
    name: 'Алина',
    subtitle: 'Ассистент клиники',
    posterUrl: '/presenter/poster.jpg',
    liveCaptions: true,
  },
});
```

| Параметр `avatar` | По умолчанию | Описание |
| - | - | - |
| `posterUrl` | обязателен | Картинка-заставка с вашего сервера. |
| `listeningVideoUrl`, `speakingVideoUrl` | нет | Беззвучные ролики-заставки «слушает» и «говорит» — оба или ни одного. Без них стоит картинка. |
| `name`, `subtitle` | «AI assistant», нет | Имя и подпись в шапке панели. |
| `quality` | настройка агента | `low`, `medium`, `high`, `very_high`. Уходит в `createSession` как `avatarQuality` — передайте его в `avatar_quality`. |
| `liveCaptions` | `false` | Последние реплики агента субтитрами под видео. |

Пока идёт видео, на нём видна плашка **AI avatar**. Если в вашей стране посетителя нужно предупреждать, что он говорит с ИИ, — это остаётся на вашей стороне: плашка помогает, но не заменяет такое уведомление.

Без виджета то же видео доступно в `VoiceClient`: событие `agentVideoChanged` (`{ available }`) сообщает, появилось ли видео, а `attachAgentVideo(element)` выводит его в ваш `<video>`.

## Требования к странице

* **HTTPS.** Без защищённого соединения браузер не даст микрофон, и `startCall` вернёт `WEBRTC_UNSUPPORTED`.
* **Content Security Policy.** Если у сайта есть CSP, разрешите: адрес, откуда грузятся файлы SDK, — в `script-src` и `style-src`; ваш сервер и адрес из поля `url` сессии (HTTPS и WSS) — в `connect-src`; `blob:` — в `media-src`. Для аватара: адрес картинки-заставки — в `img-src`, роликов — в `media-src`; с роликами ещё `style-src-attr 'unsafe-inline'`.
* **Браузеры.** Нужна поддержка WebRTC — она есть во всех современных браузерах на компьютере и телефоне.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.