Developer cookbook

발신 전화 걸기(API)

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

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

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

사전 요구 사항#

1. VoIP 번호 준비

   발신 통화를 하려면 VoIP 연결을 통해 from_number를 소유해야 합니다. 데모 번호는 수신 전용입니다. 자체 번호 가져오기를 참조하세요.

2. 에이전트 생성

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

3. 잔액 유지

   잔액이 $0.00 이하이면 발신 통화에서 402 Payment Required가 반환됩니다. POST /v1/billing/top-up을 통해 잔액을 충전하거나 자동 충전을 활성화하세요.

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

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

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
  }'

응답:

{ "call_id": 987654321, "status": "initiated" }

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

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

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 웹훅을 구독하세요. 통화가 종료되었음을 가장 빠르게 알 수 있는 방법입니다. 수신 웹훅을 받을 수 없는 경우 몇 초마다 GET /v1/calls/{call_id}를 폴링하세요. 통화가 종료되면 레코드에 end_reason, duration_seconds 및 녹음 URL이 포함됩니다.

처리할 만한 실패 모드#

보류 시간 제어#

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

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

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

다음 단계#