발신 전화 생성
아웃바운드 전화를 발신합니다. From 번호는 계정에 등록된 번호여야 합니다.
전화 발신: To에 전화번호를 입력하면 일반 전화로 발신됩니다.
- 예:
"To": "01012345678"
매니지드 에이전트: AgentId를 지정하면 콘솔에서 만든 AI 에이전트가 통화를 처리합니다.
이때 CallContext로 이번 통화에만 적용되는 요구사항(Instruction)과 참조 데이터
(Variables)를 얹을 수 있습니다. 콘솔에 저장된 에이전트 설정은 바뀌지 않으므로 같은
에이전트로 동시에 거는 다른 통화에는 영향이 없습니다. AgentId 모드 전용이라 다른
모드와 함께 보내면 400으로 거절됩니다.
Agent SDK: Url, AgentId, CallFlowId를 모두 생략하면 From 번호에 연결된
Agent SDK로 통화가 연결됩니다. Agent가 연결되어 있지 않으면 409 에러를 반환합니다.
Url, AgentId, CallFlowId는 서로 배타적입니다. 201 Created는 발신 요청이
큐에 들어갔다는 뜻이며 통화 연결 성공을 뜻하지 않습니다. 반환된 callId를
GET /v1/accounts/{accountId}/calls/{callId}로 조회해 최종 상태를 확인하세요.
AI Completion 모드는 종료되었습니다. AI 필드를 포함한 요청은 410으로 거절됩니다. Url(VoiceML), AgentId, CallFlowId 또는 Agent SDK를 사용하세요.
Authentication
API Key를 Bearer 토큰으로 전달
Path parameters
계정 ID
Request
수신 전화번호
발신 번호 (계정에 등록된 번호). CallToken을 보낼 때는 걸려온 통화의 발신자 번호를 넣습니다 — 받는 쪽에 표시할 번호입니다.
걸려온 통화의 웹훅에서 받은 값. 그 통화의 발신자 번호를 From에 넣으면 받는 쪽에 그 번호가 표시됩니다. 발신번호를 바꿔 새로 거는 것이 아니라 걸려온 전화를 넘기는 착신전환입니다. Url과 함께만 사용합니다. CallToken
통화 연결 시 VoiceML을 반환할 URL. AgentId·CallFlowId와 배타.
콘솔에서 만든 매니지드 에이전트 ID. Url·CallFlowId와 배타.
AgentId 에이전트의 이번 통화에만 적용되는 컨텍스트. Instruction·Variables 중 하나는 있어야 합니다(둘 다 비면 400).
콜 플로우(결정적 ARS) ID. 지정하면 그 플로우가 통화를 진행합니다. Url·AgentId와 동시에 사용할 수 없습니다. ID는 GET /v1/accounts/{accountId}/call-flows로 조회합니다.
콜 플로우 시작 변수. 멘트·URL·본문의 {{이름}}이 이 값으로 치환됩니다. CallFlowId와 함께일 때만 사용할 수 있습니다(단독 지정 시 400).
값은 문자열로 정규화되며 숫자·불리언도 허용합니다. 이름은 영문/숫자/밑줄이어야 하고 숫자로 시작할 수 없습니다. 최대 50개, 전체 8KB. caller·callee·recording_url·recording_duration·http_status는 통화 중 자동으로 채워지는 예약 변수라 지정할 수 없습니다(400).
지정하지 않은 {{변수}}는 빈 문자열로 치환됩니다.
벨 대기 시간 (초). 상대가 받지 않으면 이 시간 뒤 no-answer 로 종료됩니다. 미지정이거나 유효하지 않으면 30초, 600초를 넘으면 600초로 제한됩니다.
통화 상태 변경 시 콜백을 받을 URL
수신할 상태 이벤트 목록(공백 구분). 미지정 시 initiated ringing answered completed 가 적용됩니다. transfer(호전환 진행 상황)는 기본에 포함되지 않으므로 받으려면 직접 나열하세요. 전체 목록은 Webhooks.
자동응답기/음성사서함 감지(AMD). Enable=감지 후 AnsweredBy 통보(통화 계속), Hangup=음성사서함이면 자동 종료. 미설정 시 비활성(기본).
Response
발신 요청이 큐에 등록됨. 실제 연결 여부는 반환된 callId를 조회해 확인합니다.
통화 상태. 진행 중: queued(발신 대기) / ringing(벨) / in-progress(통화 중). 종료 상태(실제 종료 사유): completed(응답 후 정상 종료) / no-answer(벨은 울렸으나 무응답, Timeout 초과로 발신 취소) / busy(통화중) / rejected(수신 거절) / canceled(응답 전 발신 측 취소) / failed(시스템·망 오류). completed 만이 통화가 실제로 연결됐음을 의미합니다.
통화 시간 (초)
AMD(MachineDetection) 결과. MachineDetection 을 켠 발신 통화에만 값이 있으며, 사람 응답=human, 자동응답기/음성사서함=machine, 판정 불가=unknown. 미사용 시 null.
수신 통화에서 발신자가 번호 표시제한(*23# 등)을 걸고 건 통화면 true, 아니면 false.
번호는 from 에 그대로 전달됩니다. 통신사가 표시제한 여부를 보내지 않는 경로로 들어온
통화는 false 로 올 수 있습니다. 발신 통화와 2026-09-29 이전의 수신 통화는 null.
녹음 다운로드 경로 (녹음이 있는 통화만)
통화 종료 사유. status 가 왜 그렇게 끝났는지를 구분합니다. 종료 전이거나 사유
미상이면 null.
네 갈래로 나뉩니다 — 번호 자체가 문제라 재시도해도 소용없는 것(invalid_number 등),
일시적이라 재시도 가치가 있는 것(no_answer·user_busy 등), 번호가 아니라 계정
문제인 것(concurrency_limit_exceeded·subscription_inactive 등), ClawOps 측 오류
(app_error·call_stuck).
고객 설정이 받지 않고 거절한 수신 통화는 따로 갈립니다 — 수신 통화 차단 목록에 있는 번호
(caller_blocked), 번호 표시제한 통화 거절 설정(caller_id_restricted_rejected). 둘 다
status=rejected 이며 재시도 대상이 아닙니다.
종료 사유로 통화를 필터링하려면 Calls API를 참고하세요. 여기 값을 나열하지 않는 이유: 사유가 늘 때마다 spec·문서·대시보드가 각각 갱신돼야 하는데 한 곳만 빠지면 조용히 어긋난다(실제로 그렇게 어긋난 적이 있다).
통신망 Q.850 cause code. 1·5·28=결번, 16=정상해제, 17=통화중, 18/19/20=무응답, 21=거절, 38=망장애. 사유 미상이면 null.
종료를 유발한 SIP 응답코드 (404=없는 번호, 486=통화중, 500=망 오류 등). 수신 통화를 받지 않고 거절했으면 ClawOps 가 보낸 응답(403=거절, 486=통화중)입니다. 응답코드 없이 끝났으면 null.
종료 책임 주체. carrier(통신망) / callee(수신 측) / caller(발신 측) / app·system(ClawOps 측 — 이 경우 재시도를 권장합니다). 통화 후 정상 종료에서는 먼저 끊은 쪽의 역할입니다: 착신 통화에서 상대가 끊으면 caller, 여러분의 앱이 끊으면 callee(발신 통화는 그 반대). 판정하지 못하면 null.
전환 대상 번호. 읽기 전용 — 값을 지정하는 요청 필드는 없고 실제로 일어난 전환의 결과가 기록됩니다. 전환이 없었으면 null.
에이전트 전환과 SIP REFER 전환에서만 채워집니다(VoiceML <Dial> 은 제외 — 그 결과는
DialCallStatus 로 받습니다).
전체 설명은 통화 전환 결과 가 정본입니다.
전환 결과(읽기 전용, 전환이 없었으면 null).
completed(연결 후 정상 종료) / no-answer(대상이 받지 않음) / busy(통화중) / canceled(연결 전에 취소·중단) / failed(그 외 실패 — 사유는 transferHangupCauseQ850 · transferSipResponseCode · transferReasonText).
종료된 전환의 결과만 담습니다. 진행 중 상태는 transfers[].status 또는 Status Callback
의 transfer 이벤트로 보세요.
전환 통화 시간(초) — 대상이 받은 시점부터 그 전환 leg 가 끝날 때까지의 관측값입니다. 연결되지 못한 전환은 null.
⚠️ 과금 초가 아닙니다. 과금 대상 초는 transfers[].billableDuration 입니다.
전환 leg 의 통신망 Q.850 cause (예: 16=정상해제, 17=통화중, 19=무응답, 21=거절, 38=망장애). 통신망이 SIP 5xx 로 보낸 실패의 실제 사유로 교정된 값. 사유 미상이면 null.
전환 leg 의 실제 SIP 응답코드 (예 500). 사유 미상이면 null.
전환 실패 원본 진단 텍스트. 사유 미상이면 null.
전환 leg 정본 체인(sequence 순). 다단계/재시도 전환의 전체 이력을 제공한다. 단건 조회에만 포함되며(리스트 응답엔 생략), 전환이 없었던 통화는 빈 배열.
위 transfer* 단일 필드는 이 체인에서 파생한 하위호환용 대표 leg 다 — 종료된 leg 중 completed 우선, 동률이면 sequence 최대. 전체 시도는 이 배열로 본다.
통화 종료 시각