본문으로 건너뛰기

음성 통화

워크스페이스의 음성 통화 이벤트 기록을 읽는 조회 API입니다. 통화 목록만 제공하며 녹취 파일, 통화 요약, 전화번호는 응답에 포함되지 않습니다.

통화 목록​

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

  • Scope: voice:read
  • 쿼리: limit(기본 50, 1~100), cursor(이전 응답의 meta.next_cursor 값)
  • created_at 내림차순(최신순)으로 정렬됩니다.

범위를 벗어난 limit은 자동 보정 없이 400 INVALID_QUERY로 거부합니다. 발급 후 24시간이 지난 cursor도 같은 오류를 반환합니다. 자세한 규칙은 페이지네이션을 참고하세요.

아래 요청은 통화 기록 50건을 조회합니다.

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..." }
}

필드​

필드타입설명
idstring통화 UUID
channel_idstring연결된 채널 UUID
contact_idstring연결된 연락처 UUID
directionstring통화 방향 (아래 값 집합 참조)
statusstring통화 상태 (아래 값 집합 참조)
duration_secondsinteger통화 시간(초). 상태별 기준은 아래를 참고하세요
started_atstring통화 시작 시각 (RFC 3339)
ended_atstring통화 종료 시각 (RFC 3339)
created_atstring기록 생성 시각 (RFC 3339)

channel_id·contact_id·duration_seconds·ended_at은 값이 없으면 null이 아니라 키가 생략됩니다 ("key" in obj로 판별).

  • channel_id·contact_id: 연결 대상이 없거나, 연결됐던 채널이나 연락처가 삭제된 통화에서 빠집니다.
  • duration_seconds·ended_at: 진행 중(ringing·in_progress)인 통화에서 빠집니다.

값 집합​

필드값
directioninbound | outbound | widget_inbound (widget_inbound = 웹 위젯 방문자 통화)
statusringing | in_progress | completed | missed | failed | dropped

duration_seconds 기준​

duration_seconds는 상태별로 측정 기준이 다릅니다.

status값
completed·dropped응답(answer)부터 종료까지의 통화 시간
missed호출(ringing) 지속 시간
failed미응답 종료 시 0

duration_seconds를 단순 합산해 통화 시간으로 집계하면 missed의 호출 시간이 섞여 과대 계산됩니다.

응답에 없는 값​

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