---
title: "수신 전화 처리(API)"
description: "엔드투엔드: 에이전트를 구성하고, 전화번호에 할당하고, 전화를 받고, 통화를 검토합니다."
---
첫 에이전트를 직접 만들고 계신가요? 대시보드에서는 안내 마법사를 통해 에이전트 생성, 번호 추가, 시뮬레이션, 검토의 정확히 이 흐름을 안내합니다. [대시보드 빠른 시작](/ko/quickstart-dashboard)에서 시작하세요.
터미널에서 수행하는 표준적인 "AI로 전화를 받는" 흐름입니다.
다음을 수행합니다.
1. 프롬프트와 음성이 포함된 에이전트를 생성합니다.
2. 전화번호를 프로비저닝하거나 가져온 뒤, 에이전트를 해당 번호의 인바운드 처리기로 할당합니다.
3. 번호로 전화를 겁니다. 통화 로그, 트랜스크립트, 녹음을 확인합니다.
총 API 호출: 4회. 총 소요 시간: 5분 미만.
## 1. 에이전트 생성
에이전트는 통화를 수행하는 프롬프트, 음성, 제품 티어를 묶습니다.
에이전트에서 `max_call_duration_seconds` 및
`ring_duration_seconds`와 같은 통화 제한도 설정할 수 있습니다. 에이전트는 또한 에이전트가 말하기 전에
사전 녹음된 인트로와 최대 두 번의 벨소리를 재생하는 `intro_clip` 및
`intro_ring_count`를 지원합니다. 새 에이전트에는 시간대도 필요합니다.
모든 구성 필드는 [에이전트](/api-reference/agents)를 참조하세요. 최소 설정은 다음과 같습니다:
```bash
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Support",
"prompt": "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
"voice": "john",
"product": "spark"
}'
```
반환된 `id`를 저장하세요. 2단계에서 필요합니다.
가장 저렴한 비용으로 간단한 질의응답을 처리하려면 `spark`를 선택하고, 속도가 가장 중요하면 `bolt`를 선택하세요. 프롬프트에 더 깊은 추론이 필요하고 모델이 생각하는 동안 0.5초의 필러를 허용할 수 있다면 `storm-base-with-ack`로 업그레이드하세요. [제품 티어](/api-reference/agents#product-tiers-at-a-glance)를 참조하세요.
## 2. 전화번호 받기
전화할 번호만 필요하다면 ThunderPhone의 번호 풀에서 ThunderPhone 번호를 받으세요.
```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"area_code": "415"}'
```
응답에는 E.164 형식의 `id`와 `number`가 포함됩니다. ThunderPhone 번호는 `status="provisioning"` 상태로 시작하며 몇 초 내에 `active` 상태가 됩니다. 전환 상태를 확인해야 한다면 [`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)를 폴링하세요.
ThunderPhone 번호는 처음에는 인바운드 전용입니다. 조직 관리자는 전화번호 페이지에서 아웃바운드 통화를 요청할 수 있습니다. ThunderPhone은 각 요청을 수동으로 검토하며, 승인되면 해당 번호로 전화를 걸고 캠페인을 실행할 수 있습니다. 고객 VoIP 번호에는 변경이 없습니다.
## 3. 에이전트 할당
1단계의 에이전트를 번호의 인바운드 방향에 연결합니다.
```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
이제 번호가 활성화되었습니다. 조직의 아웃바운드 통화가 승인된 후에는 동일한 PATCH에서 `outbound_agent_id`도 설정할 수 있습니다. 승인 전에는 API가 해당 할당을 `400`으로 거부합니다.
고정된 `inbound_agent_id` 대신 구성 웹훅을 통해 수신 전화를 라우팅하는 경우, 이제 해당 웹훅은 `agent_id` 및 `variables`와 함께 통화별 `timezone`을 반환할 수 있습니다.
## 4. 통화 받기
휴대폰에서 해당 번호로 전화를 거세요. 에이전트가 전화를 받고 프롬프트에 따라 자신을 소개한 후 대화가 시작됩니다.
통화가 진행 중인 동안에는 [`GET /v1/calls`](/api-reference/calls#list-calls)에 `status="in_progress"`로 표시됩니다. 통화가 종료되면 레코드가 `end_reason`, `duration_seconds`, `billable_minutes`, 그리고 최종적으로 녹음 URL 및 AI 평가로 업데이트됩니다.
수신 전화는 조직의
[동시 통화 한도](/api-reference/introduction#call-limits)에 포함됩니다(기본적으로
통화 진행 중 20건이며, 발신, 웹 및 테스트 통화와 공유됩니다). 한도에 도달한 상태에서 걸려온 전화는 에이전트가
응답하기 전에 거부되고 종료되며, 요금이 청구되지 않고 종료 사유가 `concurrent_call_limit_reached`인
실패한 통화로 기록됩니다. 더 높은 한도가 필요하면 support@thunderphone.com으로 이메일을 보내세요.
## 5. 결과 확인
최근 통화 목록을 가져옵니다.
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
대화 기록을 가져옵니다.
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
녹음 URL(단기간 유효한 서명 URL)도 가져옵니다.
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
[`telephony.complete` 웹훅](/ko/webhooks/events)을
구독한 경우 동일한 데이터를 서버로 POST 요청으로 받습니다. 자세한 내용은
[call.complete](/ko/webhooks/call-complete)를 참고하세요.
에이전트에 추출 필드가 구성되어 있으면 완료된 통화 페이로드에 구조화된 추출 데이터도
포함될 수 있습니다.
---
## 다음 단계
전화번호 또는 웹훅의 사용자 지정 로직에 따라 발신자마다 다른 에이전트를
선택합니다.
대화 중에 에이전트가 API를 호출하도록 합니다.
발신자를 직접 연결하거나 연결 전에 수신 대상을 선별합니다.
완료된 각 통화를 CRM / 분석 파이프라인으로 스트리밍합니다.
모든 통화를 자동으로 평가하고 표시된 통화를 검토 대상으로 라우팅합니다.