# 통화 중 이벤트 조회 (/docs/api/calls/listCallLiveEvents) **GET /v1/accounts/{accountId}/calls/{callId}/live-events** ```json { "operationId": "listCallLiveEvents", "tags": [ "Calls" ], "summary": "통화 중 이벤트 조회", "description": "관리형 에이전트 통화의 실시간 전사·키패드 이벤트를 `id` 순서로 반환합니다. 통화 중에도, 끝난 뒤에도 조회할 수 있습니다.\n에이전트 설정 `liveEvents.events` 에 고른 이벤트만 있습니다. 통화 중 실시간으로 받으려면\n`…/live-events/stream` 을 쓰세요.\n", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d" }, { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "CA1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6" }, { "name": "after", "in": "query", "required": false, "description": "이 `id` 다음 이벤트부터 반환합니다. 없으면 처음부터.", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$" }, "example": "18340" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "example": 200 } ], "responses": { "200": { "description": "이벤트 목록", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "관리형 에이전트 통화 중 이벤트(실시간 전사·키패드). 에이전트 설정 `liveEvents.events` 에 고른 이벤트만 생깁니다.\n모양은 통화 이벤트(`CallEvent`)와 같습니다.\n", "properties": { "id": { "type": "string", "description": "이벤트 고유 ID. 통화 안에서 늘어나는 순서이며 SSE 의 `id:` 와 같습니다. 이어서 받을 때 `after` 나\n`Last-Event-ID` 로 넘깁니다. 숫자 문자열이지만 크기 비교 외의 의미를 두지 마세요.\n", "example": "18341" }, "event": { "type": "string", "enum": [ "stream.started", "transcript.partial", "transcript.final", "dtmf.received", "dtmf.sent", "stream.ended" ], "description": "- `stream.started`: 이 통화의 이벤트 기록이 시작됐습니다.\n- `transcript.partial`: 말하는 도중의 텍스트. `detail.text` 는\n 그 발화의 **지금까지 누적 문장**입니다 — 받을 때마다 같은 `detail.utteranceId` 의 표시를 통째로 바꾸세요.\n- `transcript.final`: 한 발화의 확정 텍스트. 같은 `utteranceId` 의 `transcript.partial` 을 이 텍스트로 바꾸세요.\n 말이 끊긴 발화는 마지막 `transcript.partial` 보다 짧을 수 있습니다.\n- `dtmf.sent`: AI가 통화 미디어 연결로 보낸 키 하나. 상대 시스템의 수신 완료를 보장하지 않습니다.\n- `dtmf.received`: 키 하나. 누른 값 그대로입니다.\n- `stream.ended`: 마지막 이벤트. `detail.reason` 은 `completed`(통화 종료) · `runner_lost`(종료 기록 없이 끊김) ·\n `no_events`(이 통화엔 이벤트가 없음 — `liveEvents.events` 가 빈 에이전트이거나 관리형 에이전트 통화가 아님) 입니다.\n", "example": "transcript.final" }, "timestamp": { "type": "string", "format": "date-time", "description": "에이전트가 이벤트를 받은 시각(UTC)", "example": "2026-10-21T06:50:59.300Z" }, "detail": { "type": "object", "additionalProperties": true, "description": "이벤트별 필드.\n- `transcript.partial`·`transcript.final`: `utteranceId`(문자열), `role`(`user` 상대방 · `agent` 에이전트), `text`\n- `dtmf.sent`: `digit`(`0`–`9`, `A`–`D`, `*`, `#`). 통화 미디어 전송 성공이며 상대 ARS 인식 확인은 아닙니다.\n- `dtmf.received`: `digit`(`0`–`9`, `*`, `#`)\n- `stream.ended`: `reason`\n", "example": { "utteranceId": "u3", "role": "agent", "text": "평일 오전 9시부터 오후 6시까지입니다." } } }, "required": [ "id", "event", "timestamp", "detail" ] } }, "hasMore": { "type": "boolean", "description": "`true` 면 마지막 항목의 `id` 를 `after` 로 넘겨 이어서 조회합니다.", "example": false } }, "required": [ "data", "hasMore" ] } } } }, "404": { "description": "통화를 찾을 수 없음", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "사람이 읽을 수 있는 에러 메시지" }, "code": { "type": "string", "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n 해제해야 발신됩니다.\n - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)", "example": "recipient_blocked" }, "ip": { "type": "string", "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.", "example": "52.79.213.41" }, "processedAt": { "type": "string", "format": "date-time", "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.", "example": "2026-10-21T04:10:34.303Z" }, "blockers": { "type": "array", "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.", "items": { "type": "object", "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |", "properties": { "number": { "type": "string", "description": "422 응답의 blockers 에만 있다", "example": "07012340002" }, "code": { "type": "string", "enum": [ "number_not_owned", "number_not_carrier_issued", "business_info_incomplete", "identity_unverified", "account_restricted", "business_recheck_pending", "holder_is_personal" ], "example": "number_not_carrier_issued" }, "message": { "type": "string", "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다." } }, "required": [ "code", "message" ] } } } } } } } } } ```