Getting Started

핵심 개념

플랫폼의 모든 요소를 한눈에 살펴보세요. 각 객체의 역할, 대시보드에서의 위치, 그리고 이를 다루는 API를 확인할 수 있습니다.

ThunderPhone은 AI 음성 에이전트를 구축, 운영, 개선하기 위한 완전한 플랫폼입니다. 이 페이지는 개념을 한눈에 볼 수 있는 안내서입니다. 여기에서 만나게 될 모든 개념을 각각 짧은 섹션으로 설명하고, 관련 대시보드 화면과 이를 지원하는 API를 함께 안내합니다. 한 번 훑어본 뒤 용어를 자세히 확인해야 할 때마다 다시 찾아보세요.

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

조직#

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

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

대시보드에서: 조직 전환기(사이드바 하단) 및 조직 설정 — 내 계정, 일반, 키, 알림, 청구 설정, 청구 내역 탭입니다. 조직 설정 참조를 확인하세요.

API에서: /v1/orgs, /v1/developer/api-keys.

에이전트#

에이전트는 통화를 실행하는 AI 구성입니다. 다음을 함께 포함합니다.

• 에이전트의 발화 내용과 동작 방식을 제어하는 프롬프트입니다. 통화 전달, 키패드 입력, 통화 종료 같은 통화 작업도 별도 구성이 아닌 일반 프롬프트 줄로 포함됩니다.
• 엔진 등급(spark, bolt, storm-*)입니다. Spark는 비용에 최적화되어 있고, Bolt는 속도에 최적화되어 있으며, Storm는 복잡한 프롬프트에서의 지능에 최적화되어 있습니다.
• 음성, 기본 언어, 선택적 추가 언어입니다. 발신자가 언어를 변경하면 에이전트가 자동으로 전환합니다. 지원 언어를 확인하세요.
• 연결된 기능입니다. 연결된 앱, API 연결, 지식 베이스, MCP 서버, 인라인 함수 도구를 포함합니다.
• 발화 순서, 맞장구 모드, 배경 트랙, 대기 시간 제한과 같은 동작 설정입니다.

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

대시보드에서: 음성 에이전트 → 에이전트 빌더 (/dashboard/agents)입니다. 첫 번째 음성 에이전트 구축을 확인하세요.

API에서: /v1/agents — CRUD, 복제, 전달, 버전 기록 및 프롬프트 도우미를 제공합니다.

음성#

음성 라이브러리에는 에이전트가 사용할 수 있는 음성, 재생 가능한 샘플, 호환 언어, 성별 및 억양 그룹, 프리미엄 음성/언어 추가 요금이 포함됩니다. 유료 샘플러를 사용하면 선택 전에 직접 작성한 1–500자 문구를 합성할 수 있습니다.

자격을 충족하는 조직은 짧은 WAV 또는 MP3 샘플로 사용자 지정 음성을 만들 수도 있습니다. 사용자 지정 음성에는 할당량과 비동기 생성 상태가 있으며, 준비되면 라이브러리 음성과 동일한 에이전트 선택기에 표시됩니다.

대시보드에서: 음성 (/dashboard/voices). 음성 라이브러리 및 사용자 지정 음성을 참조하세요.

API에서: /v1/voices, 음성 샘플, 및 사용자 지정 음성.

전화번호#

전화번호는 조직에 속하며 수신 통화를 에이전트로 라우팅하고 발신 통화도 처리할 수 있습니다. 두 가지 소스가 있습니다.

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

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

대시보드에서: 전화번호 (/dashboard/phone-numbers). 전화번호 발급을 참조하세요.

API에서: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

통화#

모든 수신 통화, 발신 통화, 시뮬레이션 및 위젯 세션은 통화 로그가 됩니다. 통화에는 역할 태그가 지정된 전체 대화 기록, 도구 호출을 포함한 구조화된 턴 기록, 녹음, 청구 총액, 선택적 AI 평가 및 이슈 보고서가 포함됩니다.

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

대시보드에서: 아카이브 및 통화별 세부 정보는 통화 기록 (/dashboard/call-history)에서 확인하고, 진행 중인 통화는 실시간에서 확인합니다. 통화 검토, 청취 및 코칭을 참조하세요.

API에서: /v1/calls — 목록, 대화 기록, 기록, 오디오, 평가, 내보내기; /v1/issue-reports.

클라이언트 포털#

클라이언트 포털은 외부 고객을 위한 브랜드가 적용된 읽기 전용 통화 기록 화면입니다. 조직 관리자는 표시할 통화의 에이전트를 선택하고, 승인된 뷰어 이메일을 추가하며, 로고와 강조 색상을 업로드하고, 선택적으로 사용자 지정 도메인을 확인할 수 있습니다. 포털 뷰어는 대시보드 접근 권한 없이 통화 세부 정보, 대화 기록 및 사용 가능한 녹음을 확인할 수 있습니다.

대시보드에서: 클라이언트 포털 (/dashboard/client-portals). 클라이언트 포털을 참조하세요.

API에서: 관리자 관리 인터페이스용 /v1/client-portals.

웹 위젯#

웹 위젯은 사이트 방문자가 마이크 기반으로 에이전트와 대화할 수 있게 합니다. 전화번호는 필요하지 않습니다. 이 위젯은 허용된 도메인에 오리진이 제한된 공개 키(pk_live_...)로 인증되므로 클라이언트 측 코드에서 안전하게 사용할 수 있습니다.

키는 두 가지 모드 중 하나로 작동합니다. agent(하나의 에이전트에 정적으로 연결됨) 또는 webhook(서버가 방문자별로 구성을 선택함 — 통화별 동적 구성 참조)입니다. 위젯 세션은 전화 통화와 동일한 통화 인프라를 거칩니다.

대시보드에서: 웹 위젯(/dashboard/web-widgets) — 위젯을 만들고, 모드와 에이전트를 설정하고, 허용된 도메인을 관리하고, 삽입 스니펫을 복사합니다. 웹 위젯 만들기를 참조하세요.

API에서: /v1/publishable-key, /v1/mic-session, 그리고 위젯 SDK 문서를 참조하세요.

지식 베이스#

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

대시보드에서: 문서 라이브러리는 지식(/dashboard/knowledge)에서 관리하고, 에이전트에 연결하려면 빌더의 지식 섹션을 사용합니다. 에이전트에 지식 베이스 제공을 참조하세요.

연결#

연결은 에이전트가 외부 세계와 상호작용하는 방식입니다. 하나의 사이드바 그룹에서 네 가지 유형을 제공합니다.

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

ThunderPhone은 외부 MCP 클라이언트가 에이전트 목록을 확인하고, 통화와 대화 내용을 검사하며, 통화를 걸 수 있도록 자체 MCP 엔드포인트도 제공합니다. ThunderPhone을 MCP 서버로 사용을 참조하세요.

API에서: /v1/integrations, /v1/mcp-servers, /v1/voip-connections을 참조하세요. 도구 통합 구축도 참조하세요.

캠페인#

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

대시보드에서: 캠페인(/dashboard/campaigns)을 사용합니다. 발신 통화 캠페인 실행을 참조하세요.

일회성 프로그래밍 방식 통화의 경우: 발신 통화 API를 사용하세요.

실시간 모니터링#

실시간 화면에서는 조직 전체에서 진행 중인 모든 통화를 보여 주며, 그중 하나를 열어 실시간으로 청취하고 속삭일 수 있습니다. 새 프롬프트가 처음으로 실제 트래픽을 처리하는 모습을 확인하거나 진행 중인 캠페인을 모니터링하는 감독 화면입니다.

대시보드에서: 실시간 (/dashboard/live). 실시간 통화 모니터링 및 감독을 참조하세요.

시뮬레이션#

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

시나리오는 최소 통과율을 지정하는 스위트로 그룹화할 수 있으며, CI에서 배포 조건으로 사용할 수 있습니다. 승인된 기준선 대비 회귀는 시나리오별로 보고됩니다.

대시보드에서: 시뮬레이션 (/dashboard/simulations) 및 에이전트 빌더 내의 시뮬레이션 버튼을 사용합니다. 통화 시뮬레이션을 참조하세요.

API에서: /v1/test-calls 및 스위트 실행기를 사용합니다. 에이전트 엔드투엔드 테스트를 참조하세요.

검증 세트#

검증 세트는 실제 통화의 순간을 반복 가능한 단일 턴 회귀 검사로 전환합니다. 각 예제는 대화 컨텍스트, 관련 발신자 오디오, 원래 응답 및 예상 동작을 고정합니다. 재생은 추가 통화를 연결하지 않고 현재 에이전트 초안에 대해 실행되며, 배포 대화 상자에서는 최신 실행 결과가 해당 초안과 여전히 일치하는지 보여 줄 수 있습니다.

대시보드에서: 조직 데이터세트용 검증 세트 (/dashboard/validation) 및 실행용 에이전트 빌더의 검증 탭을 사용합니다. 검증 세트를 참조하세요.

API에서: /v1/validation-sets 및 동일한 참조 페이지의 에이전트/예제 재생 엔드포인트를 사용합니다.

실험#

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

대시보드에서: 실험 (/dashboard/experiments) 및 에이전트 빌더의 A/B 탭을 사용합니다. 실험(A/B 테스트)를 참조하세요.

이슈#

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

대시보드에서: 이슈 (/dashboard/issues) 및 통화 기록의 통화별 플래그 지정을 사용합니다. 이슈 분류를 참조하세요.

API에서: /v1/issue-reports를 사용합니다.

보고서#

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

대시보드에서: 보고서 (/dashboard/reports). 보고서를 참조하세요.

관측성#

관측성은 지표 화면입니다. 에이전트와 기간별로 필터링할 수 있는 시간 경과에 따른 통화량, 결과 및 품질을 제공하며, 후속 분석을 위해 내보낼 수 있습니다.

대시보드에서: 관측성 (/dashboard/observability). 관측성을 참조하세요.

알림#

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

대시보드에서: 조직 → 알림. 알림을 참조하세요.

웹훅#

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

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

이벤트는 두 가지 클래스로 구분됩니다.

• 차단 이벤트는 진행 중인 통화의 동작을 결정하는 구성을 서버가 응답으로 반환해야 합니다. 즉, 수신 통화 이벤트 (telephony.incoming / web.incoming)입니다. 응답 시간은 최대 10초이며, 시간 초과 시 정적으로 할당된 에이전트가 통화를 처리합니다.
• 비차단 이벤트는 지수 백오프로 재시도되는 일회성 알림입니다. 자세한 내용은 전송 의미 체계를 참조하세요.

모든 요청에는 X-ThunderPhone-Signature의 HMAC-SHA256 서명이 포함됩니다. 서명 검증을 참조하세요.

함수 도구#

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

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

대시보드에서: 빌더의 API 연결 섹션(연결 참조)입니다.

API에서: /v1/integrations 및 함수 도구 사양입니다.

팀 및 역할#

각 조직에는 두 가지 역할이 있는 구성원 목록이 있습니다. 구성원은 에이전트를 구축하고 운영하며, 관리자는 팀 및 청구도 관리합니다. 이메일로 초대할 수 있으며 초대는 7일 후 만료되고 취소할 수 있습니다. 구성원 행의 ⋯ 메뉴에서 역할을 변경하거나 구성원을 제거할 수 있습니다. 단일 로그인은 조직 전체에 설정할 수 있습니다. SSO를 참조하세요.

대시보드에서: 조직 → 일반입니다. 팀 초대를 참조하세요.

API에서: /v1/members, /v1/invites입니다.

청구#

ThunderPhone은 선불 방식입니다. 각 조직에는 USD 잔액이 있으며, 통화는 에이전트의 분당 요금으로 잔액에서 차감됩니다(엔진 등급 및 추가 요금 포함 — 빌더에서 설정을 변경하면 총 요금이 실시간으로 표시되며, 선택한 추가 언어는 분당 3¢가 추가됩니다). 잔액이 0이 되면 수신 통화는 거부되고 발신 통화는 402 Payment Required를 반환합니다.

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

대시보드에서: 조직 → 청구 설정 및 청구 내역입니다. 잔액 충전 및 자동 충전 활성화와 전체 요금 참조를 함께 참조하세요.

API에서: /v1/billing입니다.

앱 내 코파일럿#

대시보드에는 내장 코파일럿이 제공됩니다. "X는 어떻게 하나요"라고 질문하면 이 문서를 기반으로 답변하고, 실제 통제 항목을 강조하는 클릭 단위 워크스루를 제공하며, 모든 가이드 투어를 다시 재생할 수 있습니다. 이 페이지에서 언급하는 통제 항목을 찾는 가장 빠른 방법입니다. 앱 내 코파일럿에 질문하기를 참조하세요.

전체 구성#