통화 기능
결과 조회
배치 발신의 수신자별 결과 조회 방법. 상태·통화 ID·AMD 판정·콜 플로우 수집값(result) 필드와 callflow.ended webhook 으로 실시간 수신하기.
수신자별 결과 조회
curl "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/call-batches/clx1a2b3c4d5e/tasks?status=done&page=1&pageSize=50" \
-H "Authorization: Bearer $CLAWOPS_API_KEY"{
"tasks": [
{
"taskId": "clt9x8y7z6",
"to": "01012345678",
"status": "done",
"attempt": 1,
"dialRound": 1,
"nextAttemptAt": null,
"expectedDialAt": null,
"callId": "CA1a2b3c4d5e6f",
"disposition": "completed",
"answeredBy": "human",
"result": { "choice": "1", "preferred_time": "오후 2시" },
"lastError": null,
"messageKind": null,
"messageStatus": null,
"messageDeliveryStatus": null,
"messageError": null
}
]
}쿼리 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| status | string | 선택 | 상태로 필터링 — pending · dialing · done · failed · canceled · expired |
| page | integer | 선택 | 페이지 번호. 기본 1 |
| pageSize | integer | 선택 | 페이지 크기. 기본 50, 최대 500 |
응답 필드
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| taskId | string | 필수 | 수신자 항목 ID |
| to | string | 필수 | 수신 번호 |
| status | string | 필수 | pending · dialing · done · failed · canceled · expired |
| attempt | integer | 필수 | 내부 발신 시도 횟수(통신 오류 재시도 포함). 사람이 읽는 "몇 번 걸었나"는 dialRound 입니다 |
| dialRound | integer | 필수 | 실제로 벨이 울린 횟수이자 다음에 걸 차수의 인덱스입니다(0이면 다음이 1차). 발신 자체가 실패한 경우는 세지 않아, 설정한 차수가 망 장애로 소모되지 않습니다 |
| nextAttemptAt | string | 선택 | 재시도 대기가 풀리는 시각(정책상) |
| expectedDialAt | string | 선택 | 발신 가능 시간대까지 반영한 실제 예상 발신 시각. 화면에 보여줄 값은 이쪽입니다 |
| callId | string | 선택 | 발신된 통화 ID. 이 값으로 통화 상세·녹취·전사를 조회합니다. 재시도한 경우 마지막 통화의 ID 입니다 |
| disposition | string | 선택 | 통화 종료 상태 — completed · failed · busy · no-answer |
| answeredBy | string | 선택 | 자동응답기 감지 결과(human · machine · unknown). 배치를 만들 때 MachineDetection 을 켠 경우에만 채워집니다 |
| result | object | 선택 | 콜 플로우가 통화 중 수집한 변수 |
| lastError | string | 선택 | 마지막 실패 사유 |
| messageKind | string | 선택 | 미연결 문자 종류 — first(첫 통화 실패 후) · final(끝내 미연결) |
| messageStatus | string | 선택 | 문자 처리 상태 — pending · queued · failed · skipped. queued 는 통신사에 넘겼다는 뜻이지 전달 성공이 아닙니다 |
| messageDeliveryStatus | string | 선택 | 통신사 리포트로 확정된 전달 상태 — queued · sent · failed. 실제 도달 여부는 이 값으로 판단하세요 |
| messageError | string | 선택 | 문자를 보내지 못한 사유 |
status 는 배치 관점의 처리 결과이고, disposition 은 통화 자체의 종료 상태입니다.
통화가 걸렸지만 상대가 받지 않은 경우 status: "failed" + disposition: "no-answer" 처럼 함께 나타납니다.
재시도 차수를 두면 대기 중인 수신자는 status: "pending" 이면서 dialRound 가
1 이상입니다 — 아직 한 번도 안 건 대기(dialRound: 0)와 구분됩니다.
문자가 실제로 도달했는지는 messageStatus 가 아니라 messageDeliveryStatus 로 판단하세요.
messageStatus: "queued" 는 통신사에 넘겼다는 뜻일 뿐이고, 발신번호가 문자용으로 등록되지
않은 경우 등은 리포트가 도착한 뒤에야 messageDeliveryStatus: "failed" 로 드러납니다.
콜 플로우 수집값 (result)
콜 플로우로 발신한 배치라면, 통화 중 수집한 값이 result 에 담깁니다.
설문 응답, 예약 확인 여부, 녹음 URL 등 캠페인의 실제 산출물입니다.
녹음 값 듣기
녹음 블럭이 있으면 그 값은 녹음 파일의 URL 입니다. URL 자체는 만료되지 않으니 결과와 함께 보관해 두고, 필요할 때 API 키를 붙여 내려받으면 됩니다(녹음 조회 API). 녹음 파일은 90일간 보관되므로 더 오래 두어야 하면 그 전에 내려받으세요. 콘솔에서는 배치 상세 화면의 결과 표에서 바로 재생할 수 있습니다.
curl -L -H "Authorization: Bearer $CLAWOPS_API_KEY" "$RECORDING_URL" -o answer.wav녹음 블럭이 여러 개면 블럭마다 '녹음 저장' 이름을 다르게 주세요. 이름을 주지 않으면 모두
recording_url 하나를 써서 마지막 녹음만 남습니다. 통화 전체 녹음은 이 값이 아니라
통화 녹음 API 로 받는 별도 파일입니다.
통화 상세로 연결하기
callId 가 있으면 일반 통화와 똑같이 조회할 수 있습니다.
| 목적 | 엔드포인트 |
|---|---|
| 통화 상세 | getCall |
| 녹취 파일 | getRecording |
| 받아쓰기(전사) | getTranscript |
| 통화 요약 | getSummary |
폴링 대신 webhook 으로 받기
대량 배치에서 결과를 폴링하면 그만큼 요청이 늘어납니다.
콜 플로우 배치라면 callflow.ended webhook 을 등록해 두는 편이 낫습니다 —
통화 1건이 끝날 때마다 즉시 수집값이 도착합니다.
POST /v1/accounts/{accountId}/webhooks
{ "url": "https://my-app.com/callflow-webhook", "events": ["callflow.ended"] }이 webhook 의 페이로드에는 배치 ID 가 들어 있지 않습니다. 배치와 연결하려면 CallId 를 기준으로
/tasks 응답의 callId 와 맞추거나, 배치 생성 시 Tasks[].Variables 에 자체 식별자를 넣어 두세요
(주입한 변수는 Variables 에 그대로 되돌아옵니다).
진행 요약만 필요할 때
수신자 전체를 훑지 않고 진행률만 보려면 배치 상세의 counts 를 사용하세요.
curl https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/call-batches/clx1a2b3c4d5e \
-H "Authorization: Bearer $CLAWOPS_API_KEY"{ "status": "running", "counts": { "pending": 120, "dialing": 3, "done": 77, "failed": 5 } }