통화 기록 API로 검색·통계 내기: 부재중 집계와 AI 처리율 계산
KAT Cloud 통화 기록 API(GET /call-history)는 번호·키워드·채널로 검색하고 offset·limit으로 페이지를 넘깁니다. status·tag는 받아 와서 집계합니다. 부재중 건수와 AI 처리율 계산 예시를 정리했습니다.

KAT Cloud 통화 기록은 GET /call-history에 groupId를 넣고 phoneNumber(발신·수신 번호), keyword(통화 요약 내용), channelId(번호별)로 좁혀 검색합니다. 응답은 offset과 limit(기본 20, 최대 100)으로 나눠 오고 total에 전체 건수가 담깁니다. 통화 상태(status)와 응대 주체(tag)는 검색 조건이 아니라 응답 필드이므로, 부재중 건수나 AI 처리율은 기록을 받아 와서 내 쪽에서 집계합니다.
검색 조건과 응답 필드 정리
| 쿼리 파라미터 | 필수 | 용도 |
|---|---|---|
groupId | 필수 | 그룹 지정 |
channelId | 선택 | 그룹 안의 특정 번호만 |
phoneNumber | 선택 | 발신 또는 수신 번호로 검색 |
keyword | 선택 | 통화 요약(summary) 내용 검색 |
updatedAfter | 선택 | 이 시각 이후 갱신된 기록만(정렬이 updatedAt 오름차순으로 바뀜) |
offset, limit | 선택 | 페이지 시작 위치와 크기 |
집계에 쓰는 응답 필드는 status(ANSWERED·MISSED·REJECTED·UNKNOWN), tag(AI·DIRECT·AI_TO_DIRECT·UNKNOWN), isInbound, duration(초), createdAt입니다. 날짜 범위 파라미터는 없으므로 기간별 통계는 createdAt으로 거릅니다. 자세한 응답 구조는 통화 기록 목록 문서에 있고, 통화 기록 API는 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서만 쓸 수 있습니다(사용 범위).
검색 예시 세 가지
# 1) 특정 고객과의 통화 이력 (상담 화면에서 지난 통화 보여 주기)
GET /call-history?groupId=1&phoneNumber=01012345678&limit=20
# 2) 요약에 '환불'이 들어간 통화 (클레임 검토)
GET /call-history?groupId=1&keyword=환불&limit=100
# 3) 이벤트 전용 번호로 들어온 통화만
GET /call-history?groupId=1&channelId=101&limit=100keyword는 받아쓰기 전체가 아니라 요약을 검색합니다. 요약에 나오지 않은 단어는 찾지 못할 수 있으니, 꼼꼼히 찾아야 할 때는 기록을 받아 와 sttAI·sttDirect에서 직접 검색하세요. 받아쓰기 구조는 통화 받아쓰기와 요약 데이터 구조에서 설명합니다.
페이지 넘기며 모으기
total을 보고 offset을 limit만큼 늘려 가며 끝까지 받습니다. 한 번 집계하는 보고서용이라면 이 방식이 단순합니다. 다만 주기적으로 새 통화를 모으는 용도라면 전체 순회 대신 웹훅이나 updatedAfter 커서를 쓰세요. updatedAfter와 offset을 섞으면 조회 중 갱신된 기록이 끼어들어 누락이 생길 수 있습니다. 커서 방식은 통화 기록 증분 동기화에 정리되어 있습니다.
부재중 집계와 AI 처리율 계산
import os, requests
from collections import Counter
from datetime import datetime, timezone
BASE = "https://studio-gateway.zerocall.kr"
HEADERS = {"x-api-key": os.environ["KAT_API_KEY"]}
def fetch_all(group_id, **params):
offset, limit = 0, 100
while True:
r = requests.get(f"{BASE}/call-history", headers=HEADERS,
params={"groupId": group_id, "offset": offset, "limit": limit, **params}, timeout=30)
r.raise_for_status()
body = r.json()
yield from body["data"]
offset += limit
if offset >= body["total"] or not body["data"]:
break
def monthly_stats(group_id, start, end):
calls = [c for c in fetch_all(group_id)
if c["isInbound"] and start <= datetime.fromisoformat(c["createdAt"].replace("Z", "+00:00")) < end]
status = Counter(c["status"] for c in calls)
answered = [c for c in calls if c["status"] == "ANSWERED"]
tag = Counter(c["tag"] for c in answered)
handled = tag["AI"] + tag["DIRECT"] + tag["AI_TO_DIRECT"]
return {
"inbound": len(calls),
"missed": status["MISSED"],
"missed_rate": round(status["MISSED"] / len(calls) * 100, 1) if calls else 0,
"ai_resolved_rate": round(tag["AI"] / handled * 100, 1) if handled else 0,
"ai_first_rate": round((tag["AI"] + tag["AI_TO_DIRECT"]) / handled * 100, 1) if handled else 0,
"avg_duration_sec": round(sum(c["duration"] for c in answered) / len(answered)) if answered else 0,
}
print(monthly_stats(1, datetime(2026, 10, 1, tzinfo=timezone.utc), datetime(2026, 11, 1, tzinfo=timezone.utc)))지표는 이렇게 정의했습니다. 숫자 예시로 감을 잡아 보면, 한 달 받은 전화 1,200통 중 MISSED가 60통, 응답한 1,140통의 tag가 AI 800·AI_TO_DIRECT 240·DIRECT 100이라면 다음과 같습니다.
| 지표 | 계산식 | 예시 값 |
|---|---|---|
| 부재중률 | MISSED ÷ 받은 전화 | 60 ÷ 1,200 = 5.0% |
| AI 단독 처리율 | AI ÷ (AI + DIRECT + AI_TO_DIRECT) | 800 ÷ 1,140 ≈ 70.2% |
| AI 1차 응대율 | (AI + AI_TO_DIRECT) ÷ 같은 분모 | 1,040 ÷ 1,140 ≈ 91.2% |
| 직원 연결률 | AI_TO_DIRECT ÷ (AI + AI_TO_DIRECT) | 240 ÷ 1,040 ≈ 23.1% |
UNKNOWN은 분모에서 뺐습니다. 직원 연결률이 높다면 넘어간 통화의 사유부터 보세요. 사유를 모으는 방법은 AI 상담원 연결(핸드오프) 설계에 있습니다.
운영할 때 챙길 점
- 요청 한도: API는 60초에 1,200회까지입니다. 그룹이 많다면 그룹 사이에 간격을 둡니다(에러와 요청 한도).
- 응답 크기: 응답 하나가 받아쓰기 때문에 수백 KB가 될 수 있습니다. 통계만 필요하면 필요한 필드만 저장하고 나머지는 버립니다.
- 시간대:
createdAt은 ISO 8601(UTC 표기)입니다. 한국 기준 월 통계라면 경계를 KST로 바꿔 잡습니다. - 녹음 링크: 응답의 녹음 URL은 1시간 뒤 만료되므로 통계 배치에서 링크를 저장해 두지 마세요.
KAT Cloud 가입하기로 시작하거나, 대시보드 연동 구성이 필요하다면 도입 상담을 신청하세요. 통화 기록 API의 위치는 기능 목록에서도 볼 수 있습니다.
자주 묻는 질문
통화 기록 API에서 부재중 전화만 골라 조회할 수 있나요?
KAT Cloud 통화 기록 API(GET /call-history)에는 status 검색 파라미터가 없습니다. 기록을 받아 온 뒤 응답의 status 값이 MISSED인 것만 골라 집계하면 됩니다. 부재중을 바로 알아야 한다면 CALL_COMPLETED 웹훅에서 status를 확인하는 방식이 더 빠릅니다.
keyword 검색은 무엇을 찾나요?
KAT Cloud 통화 기록 API의 keyword 파라미터는 통화 요약(summary) 내용을 검색합니다. 받아쓰기 전문에서 찾아야 한다면 기록을 받아 와 sttAI·sttDirect의 text를 직접 검색하세요.
AI 처리율은 어떻게 계산하는 것이 좋나요?
KAT Cloud 통화 기록의 tag 값으로 계산합니다. 응답한 통화 중 AI 비율을 AI 단독 처리율로, AI와 AI_TO_DIRECT를 합친 비율을 AI 1차 응대율로 나눠 보면 AI가 끝까지 맡은 몫과 먼저 받은 몫을 함께 볼 수 있습니다. 어느 기준을 쓰든 UNKNOWN은 분모에서 빼고, 기간과 정의를 고정해 비교하세요.
- #통화 기록 API
- #통화 통계
- #부재중 전화
- #AI 처리율
- #Python



