통화 실패 사유 (Hangup Cause)

통화 실패 사유 (Hangup Cause)

status 는 통화가 어떻게 끝났는지(completed / failed / busy / no-answer ...)만 알려줍니다. 왜 그렇게 끝났는지 — 결번인지, 상대가 안 받은 건지, 망 장애인지 — 는 hangupCause 로 구분합니다.

특히 failed 는 결번·망 오류·시스템 오류를 모두 포함하는 대분류입니다. 발신 리스트를 정제하거나 재시도 여부를 판단하려면 status 가 아니라 hangupCause 를 보세요.

어디서 받나요

{
  "callId": "CAabcdef1234567890",
  "status": "failed",
  "to": "07080588491",
  "duration": 0,
  "hangupCause": "invalid_number",
  "hangupCauseQ850": 1,
  "sipResponseCode": 404,
  "hangupSource": "carrier"
}

재시도 판단

가장 흔한 용도입니다. 이 표만 보고 분기하면 됩니다.

재시도해도 소용없음 — 번호를 목록에서 제외하세요

재시도 가치 있음 — 일시적인 사유입니다

계정 한도·상태 — 번호가 아니라 계정을 확인하세요

수신 통화가 계정 설정 때문에 연결되지 못한 경우입니다. 상대 번호에는 문제가 없습니다.

수신 통화 차단 — 여러분의 설정이 거절했습니다

수신 통화를 받지 않고 거절하도록 여러분이 설정한 경우입니다. 실패가 아니며 요금도 청구되지 않습니다. status 는 rejected 입니다. 설정 방법은 수신 통화 차단 을 보세요.

recipient_blocked(발신 쪽 수신거부 명단)와 다릅니다 — 그쪽은 여러분이 거는 통화를 막습니다.

등록 단말·SIP 도착지 — 받는 쪽 설정을 확인하세요

번호 라우팅을 소프트폰(등록 단말 착신) 이나 SIP 트렁크(외부 SIP 도착지) 로 둔 번호에 걸려온 전화를 넘기지 못한 경우입니다. 등록 단말은 softphone_not_registered, SIP 도착지는 sip_endpoint_not_found 로 경로가 갈립니다.

단말이나 도착지가 받지 않거나 통화 중·거절로 응답하면 통신망과 같은 사유(no_answer·user_busy·call_rejected 등)로 기록됩니다. 벨이 울린 뒤 30초 안에 받지 않으면 status 는 no-answer, hangupCause 는 no_answer 입니다.

ClawOps 측 오류 — 재시도하세요

실패가 아닌 종료

사유로 조회하기

통화 목록 조회 의 hangupCause 로 필터링합니다. status 는 failed 하나에 결번·망 오류·시스템 오류가 다 섞여 있어, 사유별로 보려면 이쪽을 쓰세요.

GET /v1/accounts/{accountId}/calls?hangupCause=concurrency_limit_exceeded
GET /v1/accounts/{accountId}/calls?hangupCause=invalid_number&hangupCause=number_changed

기간·통화시간과 함께 좁힐 수도 있습니다. since/until 은 시작 시각 기준이고 until 은 미포함, minDuration/maxDuration 은 초 단위로 양끝을 포함합니다. 통화 시간이 아직 확정되지 않은 통화(진행 중 등)는 minDuration/maxDuration 을 주면 결과에서 빠집니다.

# 지난달 놓친 전화 중 0초로 끝난 것만
GET /v1/accounts/{accountId}/calls?since=2026-08-01T00:00:00Z&until=2026-09-01T00:00:00Z&minDuration=0&maxDuration=0

hangupSource — 누구 때문에 끝났나

통화 후 정상 종료(normal_clearing)에서 caller·callee 는 먼저 끊은 쪽의 역할입니다. 여러분의 앱·에이전트가 끊었다면 그 통화에서 맡은 역할로 기록됩니다.

sipResponseCode

통신망이 보낸 SIP 응답코드가 있을 때만 채워집니다. 없이 끝난 통화는 null 입니다.

예제 — 결번 자동 정제

발신 후 통화 결과를 조회해, 다시 걸어도 소용없는 번호를 목록에서 빼는 예제입니다.

DO_NOT_RETRY = {"invalid_number", "number_changed", "incompatible_destination"}

call = client.accounts(account_id).calls.get(call_id)

if call.status != "completed":
    cause = getattr(call, "hangup_cause", None)
    if cause in DO_NOT_RETRY:
        mark_number_invalid(call.to)          # 고객 DB 에서 제외
    elif getattr(call, "hangup_source", None) in ("app", "system"):
        enqueue_retry(call.to)                # ClawOps 측 오류 — 재시도
    else:
        enqueue_retry(call.to, delay_min=30)  # 일시적 사유 — 나중에 재시도

Status Callback 으로 실시간 처리하려면 종료 이벤트에서 같은 값을 읽으면 됩니다.

@app.route("/status", methods=["POST"])
def status_callback():
    if request.form.get("CallStatus") in ("completed", "failed", "busy", "no-answer"):
        cause = request.form.get("HangupCause")
        if cause in DO_NOT_RETRY:
            mark_number_invalid(request.form.get("To"))
    return "", 204

통화 전환(transfer)의 실패 사유

이 페이지의 hangupCause 는 발신자와 ClawOps 사이의 통화(메인 leg) 에 대한 값입니다. 에이전트나 SIP 단말이 상담원에게 넘긴 전환 leg 는 별도 필드를 씁니다 — transferHangupCauseQ850 · transferSipResponseCode · transferReasonText, 그리고 다단계 전환의 전체 이력은 transfers[] 입니다. 값을 읽는 법은 통화 전환 결과 를 보세요.

VoiceML <Dial> 은 이 transfer* 필드를 채우지 않습니다. <Dial> 결과는 action 요청의 DialCallStatus 로 받습니다 — VoiceML 참고.