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

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

<Note>
  cURL 없이도 모두 수행할 수 있습니다. **웹 위젯** 대시보드
  페이지(`/dashboard/web-widgets`)에서 위젯을 생성하고, 모드와 에이전트를
  설정하며, 허용 도메인을 관리하고, 임베드 스니펫을 제공합니다.
</Note>

## 사전 요구 사항

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

## 배포용 키 생성

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

```bash 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"]
  }'
```
</CodeGroup>

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

<Warning>
  `allowed_domains`에는 하나 이상의 항목이 있어야 합니다. `*.example.com`은
  하위 도메인(예: `api.example.com`)과 일치하지만 기본
  도메인과는 **일치하지 않습니다**. `*` 또는 `*.*` 같은 단독 와일드카드는 거부됩니다.
</Warning>

## 사이트에 위젯 추가

세 가지 통합 옵션은
[위젯 SDK 문서](/ko/widget/overview)에서 설명합니다.

<CardGroup cols={3}>
  <Card title="React 컴포넌트" icon="react" href="/ko/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="헤드리스 훅" icon="circle-nodes" href="/ko/widget/headless-hook">
    맞춤 UI용 `useThunderPhone()`.
  </Card>
  <Card title="CDN 스크립트 태그" icon="code" href="/ko/widget/cdn-script-tag">
    번들러를 사용하지 않는 사이트용 `ThunderPhone.mount({...})`.
  </Card>
</CardGroup>

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

## 브라우저 재정의

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

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

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

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

```json
{
  "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토큰), [프롬프트 크기 할증](/ko/guides/billing-and-topups)에 포함됩니다. 에이전트에는 이를 지시가 아닌 페이지 콘텐츠로 취급하도록 전달됩니다.

## 위젯 모드 웹훅

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

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

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

## 세션 관찰

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

---

## 다음 단계

<CardGroup cols={2}>
  <Card title="위젯 SDK 레퍼런스" icon="window-maximize" href="/ko/widget/overview">
    React / hook / CDN 통합 세부 정보입니다.
  </Card>
  <Card title="통화별 동적 구성" icon="bolt" href="/ko/guides/dynamic-call-config">
    `mode="webhook"` 흐름을 처음부터 끝까지 구현합니다.
  </Card>
  <Card title="배포 가능 키 레퍼런스" icon="key" href="/api-reference/publishable-keys">
    키 리소스의 모든 필드입니다.
  </Card>
  <Card title="마이크 세션 API" icon="microphone" href="/api-reference/mic-sessions">
    위젯을 건너뛰고 맞춤 UI를 위해 LiveKit을 직접 사용합니다.
  </Card>
</CardGroup>