삽입 가능한 음성 위젯

ThunderPhone 임베더블 음성 위젯을 사용하면 웹사이트 방문자가 브라우저에서 직접 AI 에이전트와 대화할 수 있습니다. 전화 통화는 필요하지 않습니다 — 사용자가 버튼을 클릭하면 ThunderPhone으로 구동되는 실시간 음성 대화가 시작됩니다. 이 위젯은 밝은 테마와 어두운 테마에 맞춰 조정되는 글래스모피즘 바 형태로 렌더링되며, 강조 색상과 위치를 맞춤 설정할 수 있습니다. @thunderphone/widget npm 패키지로 배포되며, 번들러를 사용하지 않는 환경에서는 CDN을 통해서도 이용할 수 있습니다.

ThunderPhone widget in light and dark themes with various accent colors

사전 요구 사항

위젯을 임베드하기 전에 ThunderPhone 대시보드에서 다음 세 단계를 완료합니다.

게시 가능한 API 키 생성

대시보드 설정에서 Developers로 이동하여 게시 가능한 키를 생성합니다. 게시 가능한 키는 pk_live_로 시작하며 클라이언트 측 코드에 포함해도 안전합니다.

허용 도메인 구성

동일한 Developers 설정에서 위젯을 임베드할 도메인을 추가합니다. 개발 환경에서는 항상 localhost가 허용됩니다. 와일드카드를 지원합니다(예: *.example.com).

웹 위젯 생성

대시보드에서 Web Widgets로 이동하여 위젯을 생성합니다. 노출할 에이전트와 사용할 게시 가능한 키를 선택합니다. 에이전트는 게시 가능한 키 구성에서 자동으로 확인됩니다.

게시 가능한 키(pk_live_...)는 비밀 API 토큰과 다릅니다. 게시 가능한 키는 클라이언트 측 사용을 위해 설계되었으며 허용된 도메인의 위젯 세션으로 범위가 제한됩니다. 클라이언트 측 코드에서 비밀 API 토큰을 사용하지 마세요.

빠른 시작

패키지를 설치합니다.

npm install @thunderphone/widget

앱에 위젯을 추가합니다.

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}

이것으로 완료됩니다. 사용자는 한 번의 클릭으로 AI 에이전트에 연결되는 글래스모피즘 통화 바를 보게 됩니다.

맞춤 설정

위젯에는 모양을 설정하는 네 가지 prop이 있습니다.

Prop	기본값	설명
`theme`	`'light'`	흰색 유리 효과에는 `'light'`, 어두운 유리 효과에는 `'dark'`
`primaryColor`	`'#000000'` (밝음) / `'#ffffff'` (어두움)	시작 버튼, 파형 및 연결 표시기의 강조 색상
`title`	`'Voice assistant'`	위젯에 표시되는 텍스트
`position`	`'bottom-right'`	뷰포트 모서리: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>

추가로 세 가지 prop은 모양이 아닌 세션을 맞춤 설정합니다 — 모두 통화가 시작될 때 세션 요청으로 전달됩니다.

Prop	설명
`language`	세션별 언어 재정의 — `en`, `es`, `fr-FR` 등의 코드 또는 로캘
`voice`	세션별 음성 재정의 — `maria`와 같은 음성 이름
`context`	에이전트에 전달되는 사실 기반 페이지 또는 사이트 컨텍스트(서버 측에서 12,000자로 잘림)

전체 prop 표는 React 컴포넌트 참조를 확인하세요. 완전히 맞춤화된 UI가 필요한 경우 헤드리스 훅을 사용하여 자체 인터페이스를 구축하면서 음성 세션을 관리합니다. 이 훅은 오디오 반응형 시각화를 구축할 수 있도록 실시간 오디오 레벨을 제공합니다.

통합 옵션

스택에 맞는 통합 방식을 선택합니다.

React 컴포넌트

통화 제어 및 상태 표시 기능이 내장된 사전 구축 UI 컴포넌트입니다. 가져오고, props를 전달하면 완료됩니다.

헤드리스 훅

UI를 완전히 제어할 수 있습니다. 자체 인터페이스를 구축하는 동안 useThunderPhone 훅이 음성 세션을 관리합니다.

CDN / 스크립트 태그

번들러가 필요하지 않습니다. 정적 사이트, WordPress 및 기타 React 이외 환경에서는 스크립트 태그로 위젯을 로드합니다.

스타일링

위젯에는 theme prop으로 제어하는 기본 제공 라이트 및 다크 테마와 primaryColor prop으로 제어하는 강조 색상이 포함되어 있습니다. 더 세부적으로 사용자 지정하려면 CSS 사용자 정의 속성과 클래스를 재정의할 수 있습니다. 자세한 내용은 스타일링 가이드를 참조합니다.

도움이 필요하신가요? support@thunderphone.com으로 문의하세요.

​사전 요구 사항

​빠른 시작

​맞춤 설정

​통합 옵션

React 컴포넌트

헤드리스 훅

CDN / 스크립트 태그

​스타일링

사전 요구 사항

빠른 시작

맞춤 설정

통합 옵션

스타일링