음성 통화

통화 목록

GET /voice/calls — 음성 통화 이벤트 기록을 cursor pagination으로 조회합니다.

Scope: voice:read
쿼리: limit(기본 50, 최대 100), cursor
limit이 [1, 100] 범위를 벗어나면 묵시적 보정 없이 400 INVALID_QUERY를 반환합니다.
cursor는 발급 후 24시간이 지나면 만료됩니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/voice/calls?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "c1a2b3d4-...",
      "channel_id": "ch-5e6f-...",
      "contact_id": "a1b2c3d4-...",
      "direction": "inbound",
      "status": "completed",
      "duration_seconds": 132,
      "started_at": "2026-05-01T10:00:00Z",
      "ended_at": "2026-05-01T10:02:12Z",
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "eyJ..." }
}

created_at 기준 최신순으로 정렬됩니다.

필드 값 집합

필드	값
`direction`	`inbound` \| `outbound` \| `widget_inbound` (`widget_inbound` = 웹 위젯 방문자 통화)
`status`	`ringing` \| `in_progress` \| `completed` \| `missed` \| `failed` \| `dropped`

duration_seconds는 상태별로 측정 기준이 다릅니다: completed·dropped 통화는 응답(answer)부터 종료까지의 통화 시간, missed는 호출(ringing) 지속 시간, failed는 미응답 종료 시 0입니다. 따라서 duration_seconds를 단순 합산해 통화 시간으로 집계하면 missed의 호출 시간이 섞여 과대 계산됩니다.

channel_id·contact_id·duration_seconds·ended_at은 값이 없으면 null이 아니라 키가 생략됩니다 ("key" in obj로 판별) — 연결 대상이 없거나 연결됐던 채널/연락처가 삭제된 통화는 channel_id/contact_id가 (FK는 삭제 시 NULL 처리됨), 진행 중(ringing·in_progress)인 통화는 duration_seconds/ended_at이 빠집니다.

녹취 파일 URL과 통화 요약·전사(transcript)는 이 엔드포인트로 노출되지 않습니다. 녹취는 별도 테이블에 저장되며 PII 보호를 위해 의도적으로 제외됩니다. 또한 전화번호(발신·수신)와 벤더 세션 토큰 등 내부 라우팅 상태도 응답에 포함되지 않습니다.

통화 목록​

통화 목록