Developer cookbook

웹 위젯 삽입

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

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

사전 요구 사항#

1. 에이전트 생성

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

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

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

배포용 키 생성#

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"]
  }'

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 문서에서 설명합니다.

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

위젯 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으로 필터링하여 위젯 전용 대시보드를 구축합니다.

다음 단계#