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 가 적용됩니다. transfer(호전환 진행 상황)는 기본에 포함되지 않으므로 받으려면 직접 나열하세요. 전체 목록은 Webhooks.

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).

종료 사유로 통화를 필터링하려면 Calls API를 참고하세요. 여기 값을 나열하지 않는 이유: 사유가 늘 때마다 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.

에이전트 전환과 SIP REFER 전환에서만 채워집니다(VoiceML <Dial> 은 제외 — 그 결과는 DialCallStatus 로 받습니다).

전체 설명은 통화 전환 결과 가 정본입니다.

transferStatusenum or nullOptional

전환 결과(읽기 전용, 전환이 없었으면 null).

completed(연결 후 정상 종료) / no-answer(대상이 받지 않음) / busy(통화중) / canceled(연결 전에 취소·중단) / failed(그 외 실패 — 사유는 transferHangupCauseQ850 · transferSipResponseCode · transferReasonText).

종료된 전환의 결과만 담습니다. 진행 중 상태는 transfers[].status 또는 Status Callback 의 transfer 이벤트로 보세요.

transferDurationinteger or nullOptional

전환 통화 시간(초) — 대상이 받은 시점부터 그 전환 leg 가 끝날 때까지의 관측값입니다. 연결되지 못한 전환은 null.

⚠️ 과금 초가 아닙니다. 과금 대상 초는 transfers[].billableDuration 입니다.

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 다 — 종료된 leg 중 completed 우선, 동률이면 sequence 최대. 전체 시도는 이 배열로 본다.

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