Open in

웹 위젯 삽입

단일 스크립트 태그로 마케팅 또는 지원 사이트에 음성 에이전트를 추가하세요. 방문자는 전화번호 없이 브라우저에서 바로 에이전트와 대화할 수 있습니다.

웹 위젯은 브라우저의 마이크를 사용하여 사이트 방문자가 에이전트와 클릭하여 통화하는 대화를 할 수 있게 합니다. 자체 SDK 레퍼런스가 있는 별도의 JavaScript / React SDK이며, 이 가이드는 위젯에 필요한 ThunderPhone 측 설정에 중점을 둡니다.

사전 요구 사항

에이전트 만들기
프롬프트와 음성이 위젯 세션을 실행할 에이전트입니다. widget_enabled: true(기본값)로 설정합니다.
라우팅 모드 결정하기
- mode="agent" — 키당 하나의 고정 에이전트입니다. 가장 간단합니다.
- mode="webhook" — 서버가 방문자별로 에이전트를 선택합니다. web.incoming 웹훅을 통해 선택합니다. 로그인한 사용자, A/B 테스트 또는 페이지별 라우팅에 사용합니다.
허용된 도메인 나열하기
위젯을 삽입할 모든 호스트 이름을 지정합니다. 브라우저는 각 세션 요청과 함께 페이지의 오리진을 전송하므로, 누군가 키를 다른 사이트에 복사했을 때 목록에 없는 키가 작동하지 않도록 합니다. 이는 인증이 아닙니다. 브라우저 외부의 스크립트는 어떤 Origin 헤더든 전송할 수 있습니다. 프로덕션에서는 localhost가 자동으로 허용되지 않습니다. 프로덕션 API를 대상으로 로컬에서 테스트하려면 목록에 localhost를 추가합니다.
브라우저 재정의 선택하기
페이지에서 전송할 수 있는 세션 설정을 결정합니다. 새 키는 아무것도 허용하지 않습니다. 브라우저 재정의를 참조합니다.

배포용 키 생성

Static agent

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

Dynamic via webhook

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

응답에는 pk_live_...로 시작하는 key가 포함됩니다. 배포용 키는 공개되도록 설계되었습니다 — 프런트엔드 번들에 포함해도 안전합니다. 모든 필드는 배포용 키 레퍼런스를 참조하세요.

사이트에 위젯 추가

세 가지 통합 옵션은 위젯 SDK 문서에서 설명합니다.

React 컴포넌트

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

헤드리스 훅

맞춤 UI용 useThunderPhone().

CDN 스크립트 태그

번들러를 사용하지 않는 사이트용 ThunderPhone.mount({...}).

세 옵션 모두 동일한 publishableKey를 사용하며 마이크 버튼과 통화 중 오디오 요소를 렌더링합니다.

브라우저 재정의

위젯은 페이지에서 세션별 설정 네 가지를 전송할 수 있습니다.

설정	위젯 속성	변경되는 내용
`context`	`context`	페이지의 텍스트를 참고 자료로 에이전트 프롬프트에 추가합니다
`variables`	없음(원시 `POST /v1/widget/session`만 해당)	프롬프트의 `{{variable}}` 자리표시자에 사용할 값입니다
`voice`	`voice`	이 세션에서 사용할 에이전트의 음성입니다
`language`	`language`	세션이 시작되는 언어입니다

공개 키는 공개되어 있으므로 이를 가진 사람은 누구나 도메인을 위조하는 스크립트를 포함해 이러한 설정을 전송할 수 있습니다. 따라서 키에서 허용하기 전까지 각 설정은 비활성화됩니다. 대시보드에서 위젯을 생성하거나 편집할 때 브라우저 재정의에서 해당 항목을 선택하거나, Publishable keys API를 통해 allowed_overrides를 설정합니다. 페이지에서 실제로 전송하는 항목만 허용합니다.

키에서 허용하지 않는 설정을 포함한 세션 요청은 400으로 실패하며 해당 설정 이름을 반환합니다.

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

이 검사는 두 모드 모두에 적용됩니다. 웹훅 모드에서는 허용된 설정이 web.incoming 웹훅에도 전달됩니다(context는 website_context로 전달됨). 이 설정이 도입되기 전에 생성된 키는 네 가지를 모두 허용하므로 기존 임베드는 계속 작동합니다. 사용하지 않는 항목은 비활성화합니다.

위젯 context는 12,000자로 잘리며(일반적인 영어 텍스트 약 3,400토큰), 프롬프트 크기 할증에 포함됩니다. 에이전트에는 이를 지시가 아닌 페이지 콘텐츠로 취급하도록 전달됩니다.

위젯 모드 웹훅

mode="webhook"일 때 ThunderPhone은 세션이 시작될 때마다 web.incoming 페이로드와 함께 webhook_url을 호출합니다. 해당 방문자에게 실행할 에이전트 구성을 반환합니다. 이는 전화 통화와 동일한 응답 스키마를 따릅니다.

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

자체 세션의 컨텍스트(어떤 고객이 탐색 중인지, 어떤 페이지에 있는지)를 프롬프트에 포함하고, 롤아웃별로 에이전트를 교체할 수 있습니다.

세션 관찰

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

다음 단계

위젯 SDK 레퍼런스

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

통화별 동적 구성

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

배포 가능 키 레퍼런스

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

마이크 세션 API

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

웹 위젯 삽입

사전 요구 사항#

배포용 키 생성#

사이트에 위젯 추가#

브라우저 재정의#

위젯 모드 웹훅#

세션 관찰#

다음 단계#