---
title: "삽입 가능한 음성 위젯"
description: "몇 줄의 코드로 모든 웹사이트에 음성 AI 에이전트를 추가하세요"
---

ThunderPhone 임베더블 음성 위젯을 사용하면 웹사이트 방문자가 브라우저에서 직접 AI 에이전트와 대화할 수 있습니다. 전화 통화는 필요하지 않습니다 -- 사용자가 버튼을 클릭하면 ThunderPhone으로 구동되는 실시간 음성 대화가 시작됩니다.

이 위젯은 밝은 테마와 어두운 테마에 맞춰 조정되는 글래스모피즘 바 형태로 렌더링되며, 강조 색상과 위치를 맞춤 설정할 수 있습니다. `@thunderphone/widget` npm 패키지로 배포되며, 번들러를 사용하지 않는 환경에서는 CDN을 통해서도 이용할 수 있습니다.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## 사전 요구 사항

위젯을 임베드하기 전에 [ThunderPhone 대시보드](https://app.thunderphone.com)에서 다음 세 단계를 완료합니다.

<Steps>
<Step title="웹 위젯 만들기">
  대시보드에서 **웹 위젯**으로 이동하여 위젯을 만드십시오. 제공할 에이전트를 선택하십시오. 각 위젯에는 클라이언트 측 코드에 안전하게 포함할 수 있는 자체 공개 키(`pk_live_...`)가 있으며, 에이전트는 이 키로 결정됩니다.
</Step>

<Step title="허용 도메인 구성">
  동일한 위젯에서 위젯을 삽입할 도메인을 추가하십시오. 와일드카드가 지원됩니다(예: `*.example.com`). 이 목록은 다른 사이트에서 누군가 키를 복사해도 위젯이 작동하지 않도록 하지만, 브라우저 외부의 스크립트는 어떤 `Origin` 헤더든 전송할 수 있으므로 인증 수단은 아닙니다. 프로덕션에서는 `localhost`가 자동으로 허용되지 않습니다. 프로덕션 API를 대상으로 로컬 테스트하려면 목록에 추가하십시오.
</Step>

<Step title="브라우저 재정의 선택">
  페이지에서 `language`, `voice` 또는 `context`를 설정하는 경우 **브라우저 재정의**에서 각각을 켜십시오. 새 위젯은 어떤 재정의도 허용하지 않으며, 꺼진 설정이 포함된 세션 요청은 `400 override_not_allowed` 오류로 실패합니다. [브라우저 재정의](/ko/guides/embed-web-widget)를 참조하십시오.
</Step>
</Steps>

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

<Note>
  위젯 세션은 기본적으로 30분 후에 종료되며, 에이전트 자체의 최대 통화 시간이 더 짧은 경우에는 더 일찍 종료됩니다. [공개 키](/api-reference/publishable-keys)에서 키별로 `max_call_duration_seconds`를 사용해 제한을 변경하거나(최대 6시간), 에이전트 자체의 제한을 사용하려면 `null`로 설정하십시오.
</Note>

---

## 빠른 시작

패키지를 설치합니다.

```bash
npm install @thunderphone/widget
```

앱에 위젯을 추가합니다.

```tsx
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'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

추가로 세 가지 prop은 외관이 아니라 세션을 맞춤 설정합니다. 통화가 시작되면 모두 세션 요청에 전달됩니다. 각 prop은 위젯의 게시 가능 키에서 **브라우저 재정의**로 허용된 경우에만 작동하며, 그렇지 않으면 세션 요청이 `400 override_not_allowed` 오류로 실패합니다.

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

전체 prop 표는 [React 컴포넌트 참조](/ko/widget/react)를 확인하세요.

완전히 맞춤화된 UI가 필요한 경우 [헤드리스 훅](/ko/widget/headless-hook)을 사용하여 자체 인터페이스를 구축하면서 음성 세션을 관리합니다. 이 훅은 오디오 반응형 시각화를 구축할 수 있도록 실시간 오디오 레벨을 제공합니다.

각 위젯 대화는 하나의 통화입니다. 조직의 [동시 통화 한도](/api-reference/introduction#call-limits)에 포함됩니다(기본적으로 진행 중인 통화 20건이며, 전화 및 기타 통화와 공유됨). 또한 위젯에는 활성 세션 25개(또는 이보다 높은 경우 동시 통화 한도)의 제한이 있습니다. 두 제한 중 하나에 도달하면 통화가 종료될 때까지 새 대화를 시작할 수 없습니다.

---

## 통합 옵션

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

<CardGroup cols={3}>
  <Card title="React 컴포넌트" icon="react" href="/ko/widget/react">
    통화 제어 및 상태 표시 기능이 내장된 사전 구축 UI 컴포넌트입니다. 가져오고, props를 전달하면 완료됩니다.
  </Card>
  <Card title="헤드리스 훅" icon="code" href="/ko/widget/headless-hook">
    UI를 완전히 제어할 수 있습니다. 자체 인터페이스를 구축하는 동안 `useThunderPhone` 훅이 음성 세션을 관리합니다.
  </Card>
  <Card title="CDN / 스크립트 태그" icon="globe" href="/ko/widget/cdn-script-tag">
    번들러가 필요하지 않습니다. 정적 사이트, WordPress 및 기타 React 이외 환경에서는 스크립트 태그로 위젯을 로드합니다.
  </Card>
</CardGroup>

---

## 스타일링

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

<Note>
  도움이 필요하신가요? [support@thunderphone.com](mailto:support@thunderphone.com)으로 문의하세요.
</Note>