발신 전화 걸기(API)

자체 코드에서 AI 기반 발신 전화를 트리거합니다. 설문조사, 후속 조치 또는 확인 흐름에 활용할 수 있습니다.

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

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

사전 요구 사항#

1. 발신이 활성화된 번호 선택

   VoIP 연결을 통해 소유한 번호를 사용하거나, 전화번호 페이지에서 ThunderPhone 번호를 발신 통화에 사용할 수 있도록 권한을 요청합니다. ThunderPhone 번호는 처음에는 수신 전용으로 시작합니다. ThunderPhone은 각 요청을 수동으로 검토합니다. 승인되면 해당 번호로 승인된 일일 한도(00:00 UTC에 재설정)까지 전화를 걸고 캠페인을 실행할 수 있으며, 더 높은 한도를 요청할 수도 있습니다. 고객 VoIP 번호에는 일일 한도가 없으므로 발신 통화에 사용하는 것을 권장합니다. 자세한 내용은 자체 번호 사용을 참조합니다.

2. 에이전트 생성

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

3. 잔액을 양수로 유지

   잔액이 $0.00 이하이면 발신 통화는 402 Payment Required를 반환합니다. 대시보드의 조직 → 결제 설정에서 잔액을 충전하거나 자동 충전을 활성화합니다. sk_live_ 키로 GET /v1/billing을 사용해 잔액을 확인할 수 있지만, 잔액을 충전하거나 자동 충전 설정을 변경할 수는 없습니다.

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

가장 간단한 방법은 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":   "+14155552671",
    "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":   "+14155552671",
    "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이 포함됩니다.

에이전트가 통화 후 구조화된 데이터를 추출하도록 설정된 경우, 최종 처리가 완료된 후 해당 데이터가 별도로 전달됩니다.

저장된 에이전트에 통화별 변수 전달#

저장된 에이전트는 프롬프트 텍스트에서 {{name}} 또는 {{name|there}}와 같은 플레이스홀더를 사용할 수 있습니다. agent_id로 아웃바운드 통화를 시작할 때 해당 통화의 값을 포함한 variables를 전달합니다.

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

플레이스홀더 이름을 키로 하는 문자열 값을 사용합니다. 이 변수는 저장된 에이전트에 적용되며, 이 가이드의 인라인 config 예시에서는 사용하지 않습니다.

처리해야 할 장애 유형#

전체 안정적인 적격성 코드 목록과 두 가지 409 응답 형식은 아웃바운드 통화 레퍼런스를 참조합니다. 활성 번호가 요청 수락 후 통화 시작 전에 부적격 상태가 되면, 최종 확인에서 재시도할 수 없는 409 페이로드를 반환합니다.

보류 시간 제어#

수신자의 응답이 느려 길어지는 아웃바운드 통화(IVR 전화 메뉴, 대기열)는 max_hold_seconds로 제한할 수 있습니다.

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

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

다음 단계#