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

> 자체 코드에서 AI 기반 발신 전화를 트리거하여 설문조사, 후속 조치 또는 확인 흐름을 실행합니다.

발신 통화를 사용하면 대상 번호와 에이전트 구성을 ThunderPhone에 전달하여 AI가 대신 전화를 걸도록 할 수 있습니다. 일반적인 사용 사례는 다음과 같습니다.

* 예약 확인
* 설문조사 콜백
* 부재중 전화 후 "두 번째 시도" 후속 조치
* 배차 방식 알림

<Note>
  전체 목록에 전화를 거시나요? 대시보드의
  [**캠페인**](/ko/guides/outbound-campaigns) 기능은
  (`/dashboard/campaigns`) 연락처 CSV를 받아 시간대를 고려한 통화 가능 시간, 동시 처리 및 재시도 정책을 처리합니다. 이 가이드에서는 단일 프로그래밍 방식 통화를 다룹니다.
</Note>

## 사전 요구 사항

<Steps>
  <Step title="VoIP 번호 준비">
    발신 통화를 하려면 [VoIP 연결](/api-reference/voip-connections)을 통해 `from_number`를 소유해야 합니다. 데모 번호는 수신 전용입니다. [자체 번호 가져오기](/ko/guides/bring-your-own-numbers)를 참조하세요.
  </Step>

  <Step title="에이전트 생성">
    발신용 프롬프트는 일반적으로 에이전트가 자신과 통화 목적을 소개하는 것으로 시작합니다. 예: "안녕하세요, 내일 오후 3시 예약을 확인하기 위해 Acme에서 전화드렸습니다…" `outbound_speak_order`를 기본값인 `agent_first`로 설정하세요.
  </Step>

  <Step title="잔액 유지">
    잔액이 `$0.00` 이하이면 발신 통화에서 `402 Payment Required`가 반환됩니다.
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)을 통해 잔액을 충전하거나 [자동 충전](/api-reference/billing#update-auto-reload)을 활성화하세요.
  </Step>
</Steps>

## 저장된 에이전트로 통화 걸기

가장 간단한 방법은 ID로 에이전트를 참조하는 것입니다.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'
```

응답:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"`는 요청이 수락되었음을 의미할 뿐이며, 통화가 **아직 연결된 것은 아닙니다**. 실시간 상태를 확인하려면 [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)를 폴링하세요(`in_progress` → `completed` / `failed`).
</Warning>

## 인라인 구성으로 통화 걸기

에이전트로 저장할 필요가 없는 일회성 프롬프트를 사용하려면 대신 `config`를 전달하세요. 형식은 [`call.incoming` 웹훅](/ko/webhooks/call-incoming)의 응답 스키마와 일치합니다.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## 통화 추적

동시에 [`telephony.complete` 웹훅](/ko/webhooks/events)을 구독하세요. 통화가 종료되었음을 가장 빠르게 알 수 있는 방법입니다. 수신 웹훅을 받을 수 없는 경우 몇 초마다 `GET /v1/calls/{call_id}`를 폴링하세요. 통화가 종료되면 레코드에 `end_reason`, `duration_seconds` 및 녹음 URL이 포함됩니다.

## 처리할 만한 실패 모드

| 오류                                                       | 해결 방법                                                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | 잔액을 충전하거나 자동 충전을 활성화하세요                                                                                       |
| `403` 발신 차단됨(데모 번호)                                      | 대신 VoIP 번호를 가져오세요                                                                                             |
| `403` 발신 차단됨(검증되지 않은 VoIP)                               | [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number)을 실행하세요 |
| `404 from_number is not registered to this organization` | `from_number`가 소유한 전화번호와 일치하는지 확인하세요                                                                          |
| `502 Bad Gateway`                                        | 일시적인 SIP / LiveKit 실패입니다. 안전하게 재시도할 수 있습니다                                                                    |

## 보류 시간 제어

수신자가 응답하는 속도가 느려 길어지는 발신 통화
(IVR 전화 메뉴, 대기열)는 `max_hold_seconds`로 제한할 수 있습니다.

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

최근 N초 동안 사람의 음성이 수신되지 않으면 에이전트가 전화를 끊습니다. 기본값은 900(15분)입니다.

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="발신 통화 레퍼런스" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    모든 요청 필드와 오류 코드입니다.
  </Card>

  <Card title="call.complete 수신" icon="bolt" href="/ko/webhooks/call-complete">
    완료된 발신 통화를 시스템으로 스트리밍합니다.
  </Card>

  <Card title="결제" icon="credit-card" href="/api-reference/billing">
    잔액 부족으로 발신이 실패하지 않도록 자동 충전합니다.
  </Card>

  <Card title="발신 에이전트 테스트" icon="flask" href="/ko/guides/test-agents">
    프로덕션 배포 전에 발신 에이전트를 드라이 런합니다.
  </Card>
</CardGroup>