Skip to main content
웹 위젯은 브라우저의 마이크를 사용하여 사이트 방문자가 에이전트와 클릭하여 통화하는 대화를 할 수 있게 합니다. 자체 SDK 참조가 있는 별도의 JavaScript / React SDK이며, 이 가이드에서는 위젯에 필요한 ThunderPhone 측 설정에 중점을 둡니다.
cURL 없이도 모두 수행할 수 있습니다. 웹 위젯 대시보드 페이지 (/dashboard/web-widgets)에서 위젯을 만들고, 모드와 에이전트를 설정하며, 허용 도메인을 관리하고, 임베드 스니펫을 제공합니다.

​
사전 요구 사항

1

에이전트 만들기

프롬프트와 음성을 위젯 세션에서 사용할 에이전트입니다. widget_enabled: true(기본값)로 설정합니다.
2

라우팅 모드 결정

  • mode="agent" — 키당 하나의 고정 에이전트입니다. 가장 간단합니다.
  • mode="webhook" — 서버가 방문자별로 에이전트를 선택합니다. web.incoming 웹훅을 통해 선택합니다. 로그인한 사용자, A/B 테스트 또는 페이지별 라우팅에 사용합니다.
3

허용 도메인 나열

공개 키는 오리진으로 제한됩니다. 위젯을 임베드할 모든 호스트 이름을 지정해야 합니다. 로컬 개발 중에는 localhost / 127.0.0.1이 항상 허용됩니다.

​
공개 키 만들기

응답에는 pk_live_...로 시작하는 key가 포함됩니다. 공개 키는 설계상 공개됩니다 — 프런트엔드 번들에 안전하게 포함할 수 있습니다. 모든 필드는 공개 키 참조를 확인합니다.
allowed_domains에는 최소 하나의 항목이 포함되어야 합니다. *.example.com은 하위 도메인(예: api.example.com)과 일치하지만, 루트 도메인과는 일치하지 않습니다. * 또는 *.* 같은 루트 와일드카드는 거부됩니다.

​
사이트에 위젯 추가

다음 위젯 SDK 문서에서 세 가지 통합 옵션을 다룹니다.

React 구성 요소

<ThunderPhoneWidget publishableKey="pk_live_..." />.

헤드리스 훅

맞춤 UI용 useThunderPhone().

CDN 스크립트 태그

번들러를 사용하지 않는 사이트용 ThunderPhone.mount({...}).
세 옵션 모두 동일한 publishableKey를 받고, 마이크 버튼과 통화 중 오디오 요소를 렌더링합니다. 위젯 context는 12,000자로 잘립니다(일반적인 영어 텍스트 기준 약 3,400토큰). 또한 프롬프트 크기 할증에 포함됩니다.

​
위젯 모드 웹훅

mode="webhook"인 경우 ThunderPhone은 세션이 시작될 때마다 web.incoming 페이로드와 함께 webhook_url을 호출합니다. 해당 방문자에게 실행할 에이전트 구성을 반환합니다. 전화 통화와 동일한 응답 스키마를 따릅니다.
자체 세션의 컨텍스트(어떤 고객이 탐색 중인지, 어떤 페이지에 있는지)를 프롬프트에 포함하고, 배포 단계별로 에이전트를 변경할 수 있습니다.

​
세션 관찰

위젯 세션은 GET /v1/calls에 direction="widget"으로 표시되며, 전화 통화와 동일한 트랜스크립트, 녹음, 평가 및 과금이 적용됩니다. direction으로 필터링하여 위젯 전용 대시보드를 구축합니다.

​
다음 단계

위젯 SDK 레퍼런스

React / hook / CDN 통합 세부 정보입니다.

통화별 동적 구성

mode="webhook" 흐름을 처음부터 끝까지 구현합니다.

게시 가능 키 레퍼런스

키 리소스의 모든 필드입니다.

마이크 세션 API

위젯을 건너뛰고 맞춤 UI를 위해 LiveKit을 직접 구동합니다.