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

# 핵심 개념

> 플랫폼의 모든 요소를 한눈에 파악할 수 있는 안내입니다. 각 객체의 역할, 대시보드에서의 위치, 그리고 이를 다루는 API를 설명합니다.

ThunderPhone은 AI 음성 에이전트를 구축, 실행, 개선하기 위한 완전한 플랫폼입니다. 이 페이지는 안내 지도입니다. 여기에서 만나게 될 모든 개념을 대시보드 화면과 이를 지원하는 API와 함께 각각 짧은 섹션으로 설명합니다. 한 번 훑어본 뒤, 용어에 대한 추가 설명이 필요할 때마다 다시 확인하세요.

대시보드 사이드바는 이 구조를 반영합니다.

<CardGroup cols={2}>
  <Card title="핵심" icon="cube">
    [에이전트](#agents), [전화번호](#phone-numbers),
    [웹 위젯](#web-widgets), [통화](#calls),
    [지식 베이스](#knowledge-bases).
  </Card>

  <Card title="인게이지먼트" icon="megaphone">
    [실시간 모니터링](#live-monitoring) 및 아웃바운드
    [캠페인](#campaigns).
  </Card>

  <Card title="연결" icon="plug">
    에이전트에서 사용할 수 있는 [앱, API, MCP 서버 및 VoIP 제공업체](#connections).
  </Card>

  <Card title="품질 및 테스트" icon="flask">
    [시뮬레이션](#simulations), [실험](#experiments),
    [이슈](#issues), [보고서](#reports),
    [관측성](#observability).
  </Card>

  <Card title="조직" icon="building">
    [팀 및 역할](#team-and-roles), [API 키](#organizations),
    [알림](#alerts), [청구](#billing).
  </Card>

  <Card title="이벤트" icon="bolt">
    자체 코드용 [웹훅](#webhooks) 및 [함수 도구](#function-tools).
  </Card>
</CardGroup>

***

## 조직

**조직**은 테넌시 단위입니다. 에이전트, 전화번호, 통화, 키를 비롯한 모든 리소스는 정확히 하나의 조직에 속합니다. 계정은 여러 조직에 속할 수 있으며, 각 조직에는 자체 잔액, 키 및 구성원 목록이 있습니다.

**조직 → 키**에서 생성하는 `sk_live_` API 키는 하나의 조직에 연결됩니다. 이 연결 덕분에 REST API는 매우 단순합니다. 키가 이미 조직을 식별하므로 URL 경로에 조직 ID를 넣을 필요가 없습니다.

**대시보드:** 조직 전환기(사이드바 하단) 및 **조직** 설정 — 일반, 키, 알림, 청구 설정, 청구 내역 탭이 있습니다.

**API:** [`/v1/orgs`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/developer-api-keys).

***

## 에이전트

**에이전트**는 통화를 실행하는 AI 구성입니다. 다음 항목을 묶습니다.

* 에이전트가 말하는 내용과 동작 방식을 제어하는 **프롬프트** — 연결 전환, 키패드 입력, 통화 종료와 같은 통화 작업도 별도 구성이 아니라 일반 프롬프트 줄에 포함됩니다.
* **엔진 티어**(`spark`, `bolt`, `storm-*`): Spark는 비용에 최적화되어 있고, Bolt는 속도에, Storm은 복잡한 프롬프트에서의 지능에 최적화되어 있습니다.
* **음성**과 **기본 언어**, 선택 사항인 **추가 언어** — 발신자가 언어를 바꾸면 에이전트가 자동으로 전환합니다. [지원 언어](/ko/guides/supported-languages)를 참조하세요.
* 연결된 기능: [연결된 앱](#connections),
  [API 연결](#connections), [지식 베이스](#knowledge-bases),
  [MCP 서버](#connections), 인라인
  [함수 도구](#function-tools).
* 동작 설정: 발화 순서, 맞장구 모드, 배경 트랙, 보류 시간 제한.

빌더에서 수정한 내용은 **초안에 자동 저장**되며, **배포**를 클릭하기 전에는 실제 환경에 적용되지 않습니다. 모든 배포는 빌더의 **기록** 탭에 스냅샷으로 저장되므로 이전 버전을 검사하고 복원할 수 있습니다.

**대시보드:** **음성 에이전트** → 에이전트 빌더
(`/dashboard/agents`). [첫 번째 음성 에이전트 구축하기](/ko/guides/build-an-agent)를 참조하세요.

**API:** [`/v1/agents`](/api-reference/agents) — CRUD,
복제, 전송, 버전 기록 및 프롬프트 도우미를 제공합니다.

***

## 전화번호

**전화번호**는 조직에 속하며 수신 전화를 에이전트로 연결하고
발신 전화를 처리할 수도 있습니다. 두 가지 출처가 있습니다.

* **데모 번호** — ThunderPhone 풀에서 프로비저닝되는 실제 미국 번호로,
  몇 초 안에 사용할 수 있습니다. 수신 전용이며, 짧은 음성 고지와 함께
  전화를 받고 대시보드에서는 조직당 최대 10개로 제한됩니다. 첫 테스트에는
  적합하지만 프로덕션용은 아닙니다.
* **VoIP 번호** — [VoIP 연결](#connections)을 통해 자체 공급업체에서
  가져옵니다. Twilio와 Telnyx는 직접 연결되며(Telnyx는 가이드 설정을
  제공합니다), SignalWire와 Vonage는 곧 지원될 예정입니다. 현재는 모든
  SIP 트렁크를 허용하는 수동 SIP 구성으로 연결할 수 있습니다. 가져오기 및
  확인이 완료되면 VoIP 번호는 수신과 발신을 모두 지원합니다.

각 번호 행에서 라우팅 모드를 설정하고, 수신 에이전트를 선택하고,
번호에 라벨을 지정할 수 있습니다.

**대시보드:** **전화번호** (`/dashboard/phone-numbers`). [전화번호
받기](/ko/guides/get-a-phone-number)를 참조하세요.

**API:** [`/v1/phone-numbers`](/api-reference/phone-numbers),
[`/v1/voip-connections`](/api-reference/voip-connections),
[`/v1/phone-number-labels`](/api-reference/phone-number-labels).

***

## 통화

모든 수신 통화, 발신 통화, 시뮬레이션 및 위젯 세션은 **통화 로그**가
됩니다. 통화에는 역할 태그가 지정된 전체 트랜스크립트, 구조화된 턴
기록(도구 호출 포함), 녹음, 청구 합계, 선택적 AI 평가 및 이슈 보고서가
포함됩니다.

통화가 **진행 중**인 동안 통화를 열고 **청취**할 수 있습니다. 조용히
통화에 참여하므로 통화 중인 어느 누구도 사용자의 소리를 듣지 못합니다.
청취 중에는 **속삭임**을 사용할 수 있습니다. 통화 중 에이전트에게
직접 전달되는 지시를 입력하면 발신자는 이를 듣지 못하며 에이전트는
실시간으로 지시를 이행합니다.

**대시보드:** 보관 및 통화별 세부 정보는 **통화 기록**
(`/dashboard/call-history`)에서, 진행 중인 통화는 **라이브**에서
확인하세요. [통화 검토, 청취 및 코칭](/ko/guides/review-calls)을
참조하세요.

**API:** [`/v1/calls`](/api-reference/calls) — 목록, 트랜스크립트,
기록, 오디오, 평가, 내보내기;
[`/v1/issue-reports`](/api-reference/issue-reports).

***

## 웹 위젯

**웹 위젯**을 사용하면 사이트 방문자가 전화번호 없이 마이크 기반으로
에이전트와 대화할 수 있습니다. 허용된 도메인에 대해 출처가 제한되는
**공개 키** (`pk_live_...`)로 인증하므로 클라이언트 측 코드에서 안전하게
사용할 수 있습니다.

키는 두 가지 모드 중 하나로 실행됩니다. `agent`(하나의 에이전트에
정적으로 연결) 또는 `webhook`(서버가 방문자별로 구성을 선택 —
[통화별 동적 구성](/ko/guides/dynamic-call-config) 참조)입니다. 위젯
세션은 전화 통화와 동일한 통화 인프라를 통해 처리됩니다.

**대시보드:** **웹 위젯** (`/dashboard/web-widgets`) — 위젯 생성,
모드 및 에이전트 설정, 허용된 도메인 관리, 임베드 스니펫 복사를
수행합니다. [웹 위젯 만들기](/ko/guides/embed-a-web-widget-dashboard)를
참조하세요.

**API:** [`/v1/publishable-key`](/api-reference/publishable-keys),
[`/v1/mic-session`](/api-reference/mic-sessions), 그리고
[위젯 SDK 문서](/ko/widget/overview).

***

## 지식 베이스

**지식 베이스**는 에이전트가 통화 중 답변의 근거를 마련하기 위해 검색할
수 있는 문서 집합입니다. 파일을 직접 업로드하거나 Google Drive에서
가져온 다음 빌더에서 지식 베이스를 에이전트에 연결합니다. 대화에 필요할
때마다 에이전트는 내장 검색 도구로 지식 베이스를 조회합니다.

**대시보드:** 문서 라이브러리는 **지식** (`/dashboard/knowledge`)에서,
에이전트에 연결하는 작업은 빌더의 **지식** 섹션에서 수행합니다.
[에이전트에 지식 베이스 제공하기](/ko/guides/knowledge-base)를
참조하세요.

***

## 연결

연결을 통해 에이전트가 외부 세계와 상호작용합니다. 네 가지 유형이 하나의
사이드바 그룹에 있습니다.

* **앱** (`/dashboard/app-connections`) — Slack, HubSpot, Salesforce,
  Google Calendar, Google Sheets, Cal.com에 대한 OAuth 연결입니다.
  한 번 연결한 후 작업별 도구(Slack 메시지 게시, HubSpot 연락처 업서트,
  Cal.com 슬롯 예약 등)를 모든 에이전트에 토글하여 추가할 수 있습니다.
  [앱 연결](/ko/guides/connect-apps)을 참조하세요.
* **API** (`/dashboard/api-connections`) — 모든 HTTP API를 에이전트
  작업으로 전환합니다. cURL 명령을 붙여넣으면 AI 마법사가 도구 정의 초안을
  작성하며, 직접 만들 수도 있습니다. **요청 테스트** 버튼을 사용하면
  배포 전에 샌드박스 호출을 실행합니다.
  [API 연결](/ko/guides/api-connections)을 참조하세요. 이는
  [`/v1/integrations`](/api-reference/integrations)의 대시보드
  인터페이스입니다.
* **MCP** (`/dashboard/mcp-connections`) — URL로 Model Context
  Protocol 서버를 추가하고 에이전트가 해당 서버에서 제공하는 도구를
  사용하도록 합니다. [MCP 서버 추가](/ko/guides/mcp-servers)를 참조하세요.
* **VoIP** (`/dashboard/voip-connections`) — [자체 전화번호
  사용](#phone-numbers)을 위한 공급자 자격 증명입니다.
  [VoIP 공급자 연결](/ko/guides/voip-providers)을 참조하세요.

**API에서:** [`/v1/integrations`](/api-reference/integrations) 및
[`/v1/voip-connections`](/api-reference/voip-connections)을 사용합니다.
[도구 통합 구축](/ko/guides/build-tool-integration)도 참조하세요.

***

## 캠페인

**캠페인**은 대규모로 발신 전화를 걸어 줍니다. 연락처 CSV를 업로드하고,
에이전트와 발신 번호를 선택한 다음 통화 시간대(요일과 시간, 시간대 인식),
동시 실행 수, 재시도 정책(최대 시도 횟수 및 재시도할 결과 — 미응답,
음성사서함, 실패)을 설정합니다. 캠페인은 목록을 순서대로 처리하며 모든
통화를 통화 기록에 저장합니다.

**대시보드에서:** **캠페인** (`/dashboard/campaigns`)입니다.
[발신 통화 캠페인 실행](/ko/guides/outbound-campaigns)을 참조하세요.

**일회성 프로그래밍 방식 통화의 경우:** [발신 통화
API](/ko/guides/place-outbound-calls)를 사용하세요.

***

## 실시간 모니터링

**라이브**는 조직 전반에서 진행 중인 모든 통화를 표시하며, 그중 하나를
열어 실시간으로 [통화를 듣고 속삭임](#calls)을 사용할 수 있습니다.
이는 관리 화면입니다. 새 프롬프트가 처음 실제 트래픽을 처리하는 모습을
확인하거나 실행 중인 캠페인을 모니터링할 수 있습니다.

**대시보드에서:** **라이브** (`/dashboard/live`)입니다.
[실시간 통화 모니터링 및 관리](/ko/guides/monitor-live-calls)를 참조하세요.

***

## 시뮬레이션

**시뮬레이션**은 AI 발신자가 에이전트와 실제 대화를 나누는 기능입니다.
동일한 전화 경로, 실제 트랜스크립트, 실제 평가를 사용하므로 배포 전후에
테스트할 수 있습니다. 에이전트 또는 전화번호를 지정하고, 발신자 시나리오를
직접 작성하거나 에이전트의 프롬프트를 바탕으로 **AI로 시나리오를 생성**할
수 있습니다(요청하면 엣지 케이스도 포함됩니다). 그리고 통화를 실시간으로
확인할 수 있습니다.

시나리오는 최소 통과율을 고정하고 CI에서 릴리스를 차단할 수 있는
**스위트**로 그룹화됩니다. 승인된 기준선 대비 회귀는 시나리오별로
보고됩니다.

**대시보드에서:** **시뮬레이션** (`/dashboard/simulations`)과
에이전트 빌더 내부의 **시뮬레이션** 버튼을 사용합니다.
[통화 시뮬레이션](/ko/guides/simulate-a-call)을 참조하세요.

**API에서:** [`/v1/test-calls`](/api-reference/test-calls) 및 스위트
실행기를 사용합니다. [에이전트 엔드투엔드 테스트](/ko/guides/test-agents)를
참조하세요.

***

## 실험

**실험**은 실제 트래픽에서 에이전트 구성을 A/B 테스트합니다. 변형(서로 다른
프롬프트, 엔진 또는 설정)을 정의하고, 그 사이에 트래픽을 분할한 후 변형별
결과를 비교합니다. 웹훅에서 버킷 로직을 직접 구현하는 대신 사용하세요.

**대시보드에서:** **실험** (`/dashboard/experiments`)과 에이전트 빌더의
**A/B** 탭을 사용합니다.
[실험(A/B 테스트)](/ko/guides/experiments-ab-testing)를 참조하세요.

***

## 이슈

**이슈**는 특정 통화에서 표시된 문제로, 사람이 검토하여 등록하거나 AI 채점이 감지합니다. 이슈에는 심각도, 출처, 상태가 포함되며, 이슈 페이지는 분류 대기열 역할을 합니다. 필터링하고, 문제가 발생한 통화를 검토하며, 수정 사항을 추적할 수 있습니다.

**대시보드에서:** **이슈** (`/dashboard/issues`), 그리고 통화 기록에서 통화별 플래그 지정. [이슈 분류](/ko/guides/issues)를 참조하세요.

**API에서:** [`/v1/issue-reports`](/api-reference/issue-reports).

***

## 보고서

**보고서**는 선택한 에이전트와 날짜 범위로 범위를 지정하여 통화 데이터에 관한 자연어 질문("지난주에 발신자가 사람 상담을 요청한 가장 많은 세 가지 이유는 무엇인가요?")에 AI가 작성한 분석으로 답합니다.

**대시보드에서:** **보고서** (`/dashboard/reports`). [보고서](/ko/guides/reports)를 참조하세요.

***

## 관측성

**관측성**은 지표를 확인하는 화면으로, 시간에 따른 통화량, 결과, 품질을 에이전트와 기간별로 필터링하고 후속 분석을 위해 내보낼 수 있습니다.

**대시보드에서:** **관측성** (`/dashboard/observability`). [관측성](/ko/guides/observability)을 참조하세요.

***

## 알림

**알림 규칙**은 일정 기간 동안 지표(성공률, 실패율, 평균 점수, 통화량, 스위트 회귀)를 모니터링하고 설정한 임계값을 넘으면 실행됩니다. 알림은 이메일과 Slack으로 전송되며, [웹훅 엔드포인트](/ko/webhooks/endpoints)에 `alert.triggered` 이벤트를 발생시킵니다.

**대시보드에서:** **조직 → 알림**. [알림](/ko/guides/alerts)을 참조하세요.

***

## 웹훅

ThunderPhone은 통화 중과 통화 후에 이벤트가 발생하면 서버로 **HTTP POST 웹훅**을 전송합니다. 두 가지 전송 모델이 있습니다.

* **웹훅 엔드포인트**(권장): 엔드포인트별 시크릿과 엔드포인트별 이벤트 구독을 사용하여 [`/v1/developer/webhook-endpoints`](/ko/webhooks/endpoints)에서 여러 URL을 관리합니다.
* **레거시 단일 URL 웹훅**: 조직당 하나의 URL입니다. [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) 또는 **조직 → 일반**에서 관리합니다. 이전 버전과의 호환성을 위해 유지됩니다.

이벤트는 두 가지 클래스로 나뉩니다.

* **차단 이벤트**는 진행 중인 통화를 구성하는 설정을 서버가 응답으로 반환해야 합니다. 해당 이벤트는 [수신 통화 이벤트](/ko/webhooks/call-incoming) (`telephony.incoming` / `web.incoming`)입니다. 최대 10초 안에 응답해야 하며, 시간 초과 시 정적으로 할당된 에이전트가 통화를 처리합니다.
* **비차단 이벤트**는 전송 후 응답을 기다리지 않는 알림이며, 지수 백오프로 재시도됩니다. [전송 의미론](/ko/webhooks/overview)을 참조하세요.

모든 요청에는 `X-ThunderPhone-Signature`의 HMAC-SHA256 서명이 포함됩니다. [서명 검증](/ko/webhooks/overview)을 참조하세요.

***

## 함수 도구

**함수 도구**는 에이전트가 대화 중에 호출할 수 있는 HTTP 엔드포인트입니다. ThunderPhone에 OpenAI 스타일 함수 스키마와 엔드포인트 URL을 제공하면 에이전트가 호출 시점을 결정하고, ThunderPhone이 서버에서 서명된 HTTP 요청을 수행한 후 결과를 에이전트에 반환합니다.

에이전트에는 통화 전환, 키패드(DTMF) 입력 전송, 통화 종료, 보류 대기와 같은 **기본 제공 통화 기능**도 포함되어 있습니다. 도구 정의 대신 간단한 프롬프트 줄로 이를 활성화할 수 있습니다.

**대시보드에서:** 빌더의 **API 연결** 섹션([연결](#connections) 참조).

**API에서:** [`/v1/integrations`](/api-reference/integrations) 및 [함수 도구 사양](/ko/tools/overview).

***

## 팀 및 역할

각 조직에는 두 가지 역할이 있는 구성원 목록이 있습니다. **구성원**은 에이전트를 구축하고 운영하며, **관리자**는 팀과 청구도 관리합니다. 이메일로 초대할 수 있으며, 초대는 7일 후 만료되고 취소할 수 있습니다. 구성원 행의 ⋯ 메뉴에서 역할을 변경하거나 구성원을 제거할 수 있습니다. 싱글 사인온은 조직 전체에 구성할 수 있습니다. [SSO](/ko/guides/sso)를 참조하세요.

**대시보드에서:** **조직 → 일반**. [팀 초대하기](/ko/guides/invite-your-team)를 참조하세요.

**API에서:** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/invites).

***

## 청구

ThunderPhone은 **선불형**입니다. 각 조직에는 USD 잔액이 있으며, 통화 시 에이전트의 분당 요금(엔진 등급 및 추가 요금 — 설정을 변경하면 빌더에 총 요금이 실시간으로 표시되며, [프리미엄 언어](/ko/guides/supported-languages)는 분당 2¢가 추가됩니다)이 잔액에서 차감됩니다. 잔액이 0이 되면 수신 통화는 거부되고 발신 통화는 `402 Payment Required`를 반환합니다.

수동으로 충전하거나 잔액 임계값, 충전 금액, 선택적 월간 지출 한도를 설정하여 **자동 충전**을 활성화할 수 있습니다. 이렇게 하면 통화가 문장 도중에 끊기지 않습니다.

**대시보드에서:** **조직 → 청구 설정** 및 **청구 내역**. [자금 추가 및 자동 충전 활성화](/ko/guides/billing-and-topups)를 참조하세요.

**API에서:** [`/v1/billing`](/api-reference/billing).

***

## 앱 내 코파일럿

대시보드에는 기본 제공 **코파일럿**이 있습니다. "어떻게 X하나요"라고 질문하면 이 문서를 바탕으로 답변하고, 실제 컨트롤을 강조 표시하는 클릭별 워크스루를 제공하며, 가이드 투어를 다시 재생할 수 있습니다. 이 페이지에서 언급한 컨트롤을 가장 빠르게 찾는 방법입니다. [앱 내 코파일럿에 질문하기](/ko/guides/ask-the-copilot)를 참조하세요.

***

## 종합하기

<CardGroup cols={2}>
  <Card title="대시보드 빠른 시작" icon="wand-magic-sparkles" href="/ko/quickstart-dashboard">
    5단계 마법사: 에이전트 → 청구 → 번호 → 시뮬레이션 → 검토.
  </Card>

  <Card title="API 빠른 시작" icon="terminal" href="/ko/quickstart">
    동일한 첫 통화를 REST 호출 4회로 수행합니다.
  </Card>

  <Card title="대시보드 사용" icon="table-columns" href="/ko/guides/build-an-agent">
    에이전트를 구축하고, 자금을 충전하고, 번호를 확보하고, 통화를 시뮬레이션하고 검토합니다.
  </Card>

  <Card title="도구 및 데이터 연결" icon="plug" href="/ko/guides/connect-apps">
    OAuth 앱, 커스텀 API, MCP 서버 및 VoIP 제공업체.
  </Card>

  <Card title="분석 및 개선" icon="chart-line" href="/ko/guides/reports">
    보고서, 관측 가능성, 실험, 이슈 및 알림.
  </Card>

  <Card title="팀 및 계정" icon="users" href="/ko/guides/invite-your-team">
    초대 및 역할, API 키, 보안 및 SSO.
  </Card>

  <Card title="개발자 쿡북" icon="phone-arrow-down-left" href="/ko/guides/handle-inbound-calls">
    API 레시피: 수신, 발신, 동적 구성, 도구, 테스트.
  </Card>

  <Card title="웹훅 서명 검증" icon="shield-check" href="/ko/guides/verify-webhook-signatures">
    HMAC 검사를 한 번 정확히 구현하고 어디서나 재사용합니다.
  </Card>
</CardGroup>