> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 삽입 가능한 음성 위젯

> 몇 줄의 코드로 모든 웹사이트에 음성 AI 에이전트를 추가하세요

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

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

<Frame>
  <img src="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## 사전 요구 사항

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

<Steps>
  <Step title="게시 가능한 API 키 생성">
    대시보드 설정에서 **Developers**로 이동하여 게시 가능한 키를 생성합니다. 게시 가능한 키는 `pk_live_`로 시작하며 클라이언트 측 코드에 포함해도 안전합니다.
  </Step>

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

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

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

***

## 빠른 시작

패키지를 설치합니다.

```bash theme={null}
npm install @thunderphone/widget
```

앱에 위젯을 추가합니다.

```tsx theme={null}
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) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

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

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

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

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

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

***

## 통합 옵션

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

<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>