# 결과 조회 (/docs/call-batches/results)

## 수신자별 결과 조회

```bash
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"
```

```json
{
  "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`)와 구분됩니다.

`disposition: "failed"` 는 결번·망 오류를 한데 묶은 값입니다. **어떤 번호가 결번이라 다시 걸어도
소용없는지** 가려내려면 `callId` 로 [통화 단건 조회](/docs/api/calls/getCall) 후 `hangupCause` 를
보세요 — [통화 실패 사유](/docs/call-failure-causes) 에 전체 목록과 재시도 판단 기준이 있습니다.

문자가 실제로 도달했는지는 `messageStatus` 가 아니라 **`messageDeliveryStatus`** 로 판단하세요.
`messageStatus: "queued"` 는 통신사에 넘겼다는 뜻일 뿐이고, 발신번호가 문자용으로 등록되지
않은 경우 등은 리포트가 도착한 뒤에야 `messageDeliveryStatus: "failed"` 로 드러납니다.

## 콜 플로우 수집값 (`result`)

콜 플로우로 발신한 배치라면, 통화 중 수집한 값이 `result` 에 담깁니다.
설문 응답, 예약 확인 여부, 녹음 URL 등 캠페인의 실제 산출물입니다.

`result` 는 **콜 플로우(`CallFlowId`) 배치에서만** 채워집니다. 매니지드 에이전트(`AgentId`) 나
VoiceML URL(`Url`) 로 발신한 배치는 비어 있습니다 — 이 경우 통화 [전사](/docs/api/calls/getTranscript)·
[요약](/docs/api/calls/getSummary) 이나 직접 구성한 웹훅으로 결과를 받으세요.

### 녹음 값 듣기

녹음 블럭이 있으면 그 값은 녹음 파일의 URL 입니다. URL 자체는 만료되지 않으니 결과와 함께
보관해 두고, 필요할 때 API 키를 붙여 내려받으면 됩니다([녹음 조회 API](/docs/api/calls/getVerbRecording)).
녹음 파일은 **90일간 보관**되므로 더 오래 두어야 하면 그 전에 내려받으세요.
콘솔에서는 배치 상세 화면의 결과 표에서 바로 재생할 수 있습니다.

```bash
curl -L -H "Authorization: Bearer $CLAWOPS_API_KEY" "$RECORDING_URL" -o answer.wav
```


녹음 블럭이 여러 개면 블럭마다 '녹음 저장' 이름을 다르게 주세요. 이름을 주지 않으면 모두
`recording_url` 하나를 써서 **마지막 녹음만 남습니다**. 통화 **전체** 녹음은 이 값이 아니라
[통화 녹음 API](/docs/api/calls/getRecording) 로 받는 별도 파일입니다.

## 통화 상세로 연결하기

`callId` 가 있으면 일반 통화와 똑같이 조회할 수 있습니다.

| 목적 | 엔드포인트 |
| --- | --- |
| 통화 상세 | [`getCall`](/docs/api/calls/getCall) |
| 녹취 파일 | [`getRecording`](/docs/api/calls/getRecording) |
| 받아쓰기(전사) | [`getTranscript`](/docs/api/calls/getTranscript) |
| 통화 요약 | [`getSummary`](/docs/api/calls/getSummary) |

## 폴링 대신 webhook 으로 받기

대량 배치에서 결과를 폴링하면 그만큼 요청이 늘어납니다.
콜 플로우 배치라면 [`callflow.ended` webhook](/docs/webhooks/callflow) 을 등록해 두는 편이 낫습니다 —
**통화 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` 를 사용하세요.

```bash
curl https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/call-batches/clx1a2b3c4d5e \
  -H "Authorization: Bearer $CLAWOPS_API_KEY"
```

```json
{ "status": "running", "counts": { "pending": 120, "dialing": 3, "done": 77, "failed": 5 } }
```