Звонок с сайта: Web SDK
Посетитель вашего сайта нажимает кнопку и говорит с агентом из браузера — без телефонной линии, по микрофону. Для этого есть эндпоинтPOST /v1/calls/web и браузерный SDK @hubtalk-ai/web-sdk, а в SDK — готовый виджет: кнопка в углу страницы и панель звонка.
Если нужно просто дать человеку поговорить с агентом, ничего не встраивая, хватит демо-ссылки. Web SDK — для случая, когда звонок начинается на вашем сайте, на вашем домене и с переменными, которые знает ваша система.
Как это устроено
- Посетитель нажимает кнопку звонка на вашей странице.
- Страница просит ваш сервер начать звонок. Сервер вызывает
POST /v1/calls/webс API-ключом организации и получает сессию:access_tokenиurl. - Сервер отдаёт сессию странице, страница передаёт её в SDK. Дальше разговор идёт напрямую между браузером и платформой, а состояние звонка приходит в страницу событиями.
Что нужно заранее
- Агент опубликован. Звонит опубликованная версия; черновик не подключится. Привязка к телефонии для web-звонка не нужна.
- Выпущен API-ключ — раздел «API-ключи», см. Ключ доступа. Ключ хранится на вашем сервере.
- Страница открыта по HTTPS. Без защищённого соединения браузер не даст доступ к микрофону. Исключение —
localhostпри разработке.
POST /v1/calls/web
Создаёт web-звонок и выдаёт сессию для браузера. Запрос делает ваш сервер, с заголовком Authorization: Bearer <API-ключ>.
201 Created: объект звонка и три поля сессии.
Ответ целиком можно отдать странице и передать в SDK как есть: лишние поля SDK пропускает.
Ошибки
Общие ошибки ключа и лимита запросов — в «Ошибках».
Повтор запроса. Заголовок
Idempotency-Key защищает от двойного звонка при ретраях: повтор с тем же ключом в течение суток вернёт ту же сессию, второго звонка не будет. Ключ повтора — на один звонок: для следующего посетителя нужен новый.
Сессия — на один звонок. Токен живёт 2 часа и не продлевается, поэтому выдавайте новую сессию на каждый звонок, а не держите одну на открытой странице.
Звонок в Истории и вебхуках
Web-звонок сразу появляется в Истории как активный разговор канала «Web-звонок» (channel: "web", direction: "web"). Транскрипт, запись, пост-аналитика и вебхуки работают как у телефонного звонка. В сценарии переменная {{direction}} равна web — по ней агент может говорить с посетителем сайта иначе, чем по телефону.
Жизненный цикл короче телефонного: queued → ongoing → ended, без ringing и failed. Поля номеров и транка у web-звонка пустые, answered_at — null.
Установка SDK
dist, лежат готовые файлы для подключения обычным тегом <script>: voice-client.bundle.js — клиент, widget.bundle.js и widget.css — виджет. Положите их на свой сервер:
Первый звонок
На сервере — эндпоинт, который вызываетPOST /v1/calls/web и возвращает ответ странице. Пример на Node.js (Express):
startCall вызывайте внутри обработчика нажатия. Браузер разрешает звук агента и доступ к микрофону только после действия пользователя. В Safari на iPhone сетевой запрос между нажатием и startCall() может «съесть» это действие — тогда запрашивайте сессию заранее, например при открытии панели звонка.VoiceClient
Параметры
new VoiceClient(options?) — все параметры необязательны.
Методы
События
Текстовый звонок
startCall(session, { audio: false }) начинает тот же звонок без микрофона и звука: браузер не спрашивает разрешений, разговор идёт текстом через sendText() и события transcript. Это режим для посетителя, который не может или не хочет говорить вслух. Ответы агента приходят в темпе речи.
Ошибки SDK
Любой сбой — объектVoiceError: { code, message, state, cause? }. Решения принимайте по code; message — строка для логов, текст для посетителя пишете вы.
Готовый виджет
Если своя вёрстка не нужна, в пакете есть виджет: кнопка в углу страницы и панель звонка с состоянием агента, таймером, кнопками микрофона и завершения, чатом и транскриптом после звонка. Тексты виджета — на английском или русском.dist:
Стили виджета подключаются отдельным файлом
widget.css и действуют только внутри виджета — оформление вашей страницы они не меняют.
Живой аватар
В режиме'avatar' панель показывает живое видео AI-аватара: лицо, которое говорит голосом агента синхронно с речью. Видео идёт по тому же соединению, что и звук.
- Аватар включается для агента поддержкой платформы — она же задаёт, какое лицо будет в звонке. Напишите в поддержку, для какого агента нужен аватар, и уточните, какое лицо выбрано.
- Ваш сервер просит аватар полем
"avatar": trueвPOST /v1/calls/web. Виджет подсказывает, когда это нужно:createSessionполучает{ avatar, avatarQuality }, иavatarравноtrueв режиме'avatar'. Это просьба, а не гарантия: если у агента аватар не включён, звонок идёт только со звуком, ответ API не меняется. - Заставку показываете вы. Пока видео нет — до звонка, в первые секунды, если видео прервалось, — на месте аватара стоит ваша картинка
avatar.posterUrlили пара беззвучных роликов. Подберите заставку, похожую на лицо аватара, иначе смена будет заметна.
Пока идёт видео, на нём видна плашка 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 — она есть во всех современных браузерах на компьютере и телефоне.