ClawOps APICalls

발신 전화 생성

View as Markdown
아웃바운드 전화를 발신합니다. 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

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Request

This endpoint expects an object.
TostringRequired

수신 전화번호

FromstringRequired

발신 번호 (계정에 등록된 번호)

UrlstringOptional

통화 연결 시 VoiceML을 반환할 URL. AgentId·CallFlowId와 배타.

AgentIdstringOptional

콘솔에서 만든 매니지드 에이전트 ID. Url·CallFlowId와 배타.

CallContextobjectOptional

AgentId 에이전트의 이번 통화에만 적용되는 컨텍스트.

CallFlowIdstringOptional

콜 플로우(결정적 ARS) ID. 지정하면 그 플로우가 통화를 진행합니다. Url·AgentId와 동시에 사용할 수 없습니다. ID는 GET /v1/accounts/{accountId}/call-flows로 조회합니다.

Variablesmap from strings to strings or doubles or booleansOptional
콜 플로우 시작 변수. 멘트·URL·본문의 `{{이름}}`이 이 값으로 치환됩니다. CallFlowId와 함께일 때만 사용할 수 있습니다(단독 지정 시 400). 값은 문자열로 정규화되며 숫자·불리언도 허용합니다. 이름은 영문/숫자/밑줄이어야 하고 숫자로 시작할 수 없습니다. 최대 50개, 전체 8KB. `caller`·`callee`·`recording_url`·`recording_duration`·`http_status`는 통화 중 자동으로 채워지는 예약 변수라 지정할 수 없습니다(400). 지정하지 않은 `{{변수}}`는 빈 문자열로 치환됩니다.
TimeoutintegerOptional

벨 대기 시간 (초). 상대가 받지 않으면 이 시간 뒤 no-answer 로 종료됩니다. 미지정이거나 유효하지 않으면 30초, 600초를 넘으면 600초로 제한됩니다.

StatusCallbackstringOptional

통화 상태 변경 시 콜백을 받을 URL

StatusCallbackEventstringOptional

수신할 상태 이벤트 목록 (공백 구분). 기본값: initiated ringing answered completed

MachineDetectionenumOptional

자동응답기/음성사서함 감지(AMD). Enable=감지 후 AnsweredBy 통보(통화 계속), Hangup=음성사서함이면 자동 종료. 미설정 시 비활성(기본).

Allowed values:

Response

발신 요청이 큐에 등록됨. 실제 연결 여부는 반환된 callId를 조회해 확인합니다.

callIdstringOptional
statusenumOptional

통화 상태. 진행 중: queued(발신 대기) / ringing(벨) / in-progress(통화 중). 종료 상태(실제 종료 사유): completed(응답 후 정상 종료) / no-answer(벨은 울렸으나 무응답, Timeout 초과로 발신 취소) / busy(통화중) / rejected(수신 거절) / canceled(응답 전 발신 측 취소) / failed(시스템·망 오류). completed 만이 통화가 실제로 연결됐음을 의미합니다.

tostringOptional
fromstringOptional
directionenumOptional
durationinteger or nullOptional

통화 시간 (초)

accountIdstringOptional
answeredByenum or nullOptional

AMD(MachineDetection) 결과. MachineDetection 을 켠 발신 통화에만 값이 있으며, 사람 응답=human, 자동응답기/음성사서함=machine, 판정 불가=unknown. 미사용 시 null.

recordingUrlstring or nullOptional

녹음 다운로드 경로 (녹음이 있는 통화만)

hangupCausestring or nullOptional

통화 종료 사유. status 가 왜 그렇게 끝났는지를 구분합니다. 종료 전이거나 사유 미상이면 null.

네 갈래로 나뉩니다 — 번호 자체가 문제라 재시도해도 소용없는 것(invalid_number 등), 일시적이라 재시도 가치가 있는 것(no_answer·user_busy 등), 번호가 아니라 계정 문제인 것(concurrency_limit_exceeded·subscription_inactive 등), ClawOps 측 오류 (app_error·call_stuck).

전체 목록과 재시도 판단 기준은 통화 실패 사유 가 정본입니다. 여기 값을 나열하지 않는 이유: 사유가 늘 때마다 spec·문서·대시보드가 각각 갱신돼야 하는데 한 곳만 빠지면 조용히 어긋난다(실제로 그렇게 어긋난 적이 있다).

hangupCauseQ850integer or nullOptional

통신망 Q.850 cause code. 1·5·28=결번, 16=정상해제, 17=통화중, 18/19/20=무응답, 21=거절, 38=망장애. 사유 미상이면 null.

sipResponseCodeinteger or nullOptional

종료를 유발한 SIP 응답코드 (404=없는 번호, 486=통화중, 500=망 오류 등). 응답코드 없이 끝났으면 null.

hangupSourceenum or nullOptional

종료 책임 주체. carrier(통신망) / callee(수신자) / caller(발신자) / app·system(ClawOps 측 오류 — 이 경우 재시도를 권장합니다).

transferTostring or nullOptional

통화 전환 대상 번호 (전환이 없으면 null)

transferStatusenum or nullOptional

통화 전환 결과

transferDurationinteger or nullOptional

전환 후 통화 시간 (초)

transferHangupCauseQ850integer or nullOptional

전환 leg 의 통신망 Q.850 cause (예: 16=정상해제, 17=통화중, 19=무응답, 21=거절, 38=망장애). 통신망이 SIP 5xx 로 보낸 실패의 실제 사유로 교정된 값. 사유 미상이면 null.

transferSipResponseCodeinteger or nullOptional

전환 leg 의 실제 SIP 응답코드 (예 500). 사유 미상이면 null.

transferReasonTextstring or nullOptional

전환 실패 원본 진단 텍스트. 사유 미상이면 null.

transferslist of objectsOptional

전환 leg 정본 체인(sequence 순). 다단계/재시도 전환의 전체 이력을 제공한다. 위 transfer* 단일 필드는 하위호환용 대표 leg(마지막 completed). 단건 조회에만 포함되며(리스트 응답엔 생략), 전환이 없었던 통화는 빈 배열.

dateCreateddatetimeOptional
dateUpdateddatetime or nullOptional

통화 종료 시각

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
410
Gone Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error