# KAT Cloud API 문서 요약

> KAT Cloud REST API. 전화번호(그룹) 발급, 채팅 · 문자 발송, 통화 기록 · 받아쓰기 · 요약 조회, AI 상담원 설정, 웹훅 연동. 운영: 한국에이아이통신(주).

전체 문서: https://katcloud.kr/docs/api

## 기본 규칙

- Base URL: https://studio-gateway.zerocall.kr
- 인증: `x-api-key` 헤더 (KAT Cloud 콘솔에서 발급). 연결 확인은 `GET /auth-check`
- 형식: JSON, UTF-8
- Rate limit: 1,200 requests / 60초
- 문자 발신 API는 모든 사용자가, 그 외 API는 비즈니스 요금제 그룹 또는 별도 허용된 그룹이 쓸 수 있습니다(문서의 '사용 범위와 권한').

## 웹훅

- 이벤트: MESSAGE_RECEIVED, SEND_RESULT, CALL_RECEIVED, CALL_COMPLETED, INTAKE
- 등록: `POST /webhook` (eventType, url)
- 서명 검증: `X-Webhook-Signature` 헤더(v1=HMAC). 검증 코드 예시는 https://katcloud.kr/docs/api#webhook-signature

## 빠른 시작

1. `GET /group` — 가입 때 받은 070 번호·그룹 ID 확인 (더 받으려면 `POST /group/{groupId}/numbers`, 유료 요금제. KAT 키로 `POST /group` 은 403 `KC006`)
2. `POST /webhook` — CALL_COMPLETED 등 이벤트를 받을 주소 등록
3. `POST /chat-room` + `POST /chat` — 문자 발송
4. `GET /call-history?groupId=…` — 통화 기록(요약 · 받아쓰기 · 녹음)

## 아직 운영에 없는 기능 (문서에 없거나 배포 전)

- 050 안심번호: 예정
- 080 수신자부담: 예정
- 기업용 010: 예정
- 추가 번호 구매: 업데이트 중
- 대표번호 분배: 예정
- ARS 설정: 예정
- 콘솔 문자 수신함: 업데이트 중
- 알림톡 · 브랜드메시지: 예정
- 운영시간: 업데이트 중
- 멤버 · 직원별 번호: 업데이트 중
- 웹 전화: 업데이트 중

## 목차

### 시작

- [시작하기](https://katcloud.kr/docs/api#intro)
- [핵심 개념](https://katcloud.kr/docs/api#concepts)
- [인증](https://katcloud.kr/docs/api#auth)
- [사용 범위와 권한](https://katcloud.kr/docs/api#scope)

### 서비스 구성

- [그룹](https://katcloud.kr/docs/api#group)
- [목록 조회](https://katcloud.kr/docs/api#group-list)
- [번호 추가](https://katcloud.kr/docs/api#group-numbers)

### 메시지

- [채팅방](https://katcloud.kr/docs/api#chat-room)
- [목록 조회](https://katcloud.kr/docs/api#chat-room-list)
- [상세 조회](https://katcloud.kr/docs/api#chat-room-detail)
- [생성](https://katcloud.kr/docs/api#chat-room-create)
- [나가기](https://katcloud.kr/docs/api#chat-room-delete)
- [채팅](https://katcloud.kr/docs/api#chat)
- [대화 조회](https://katcloud.kr/docs/api#chat-list)
- [메시지 발송](https://katcloud.kr/docs/api#chat-send)
- [미디어 업로드](https://katcloud.kr/docs/api#chat-media)
- [문자 발송 (Deprecated)](https://katcloud.kr/docs/api#message)
- [이미지 업로드](https://katcloud.kr/docs/api#message-upload)
- [메시지 전송](https://katcloud.kr/docs/api#message-send)
- [발송 결과 조회](https://katcloud.kr/docs/api#message-result)

### 통화

- [통화 기록](https://katcloud.kr/docs/api#call-history)
- [목록 조회](https://katcloud.kr/docs/api#call-history-list)
- [상세 조회](https://katcloud.kr/docs/api#call-history-detail)

### AI 상담원

- [AI 상담원](https://katcloud.kr/docs/api#agent)
- [등록·관리](https://katcloud.kr/docs/api#agent-crud)
- [수정 이력](https://katcloud.kr/docs/api#agent-revision)
- [늘 지키는 것](https://katcloud.kr/docs/api#agent-rules)
- [상담원 매뉴얼](https://katcloud.kr/docs/api#agent-manual)
- [등록·관리](https://katcloud.kr/docs/api#agent-manual-api)
- [기록형 칸 종류](https://katcloud.kr/docs/api#agent-manual-note)
- [번호 연결](https://katcloud.kr/docs/api#agent-channel)
- [도구 (HTTP·MCP)](https://katcloud.kr/docs/api#agent-tool)
- [등록·관리](https://katcloud.kr/docs/api#agent-tool-api)
- [고객 서버가 받는 요청](https://katcloud.kr/docs/api#agent-tool-request)
- [MCP 서버](https://katcloud.kr/docs/api#agent-tool-mcp)
- [시험 호출·새로고침](https://katcloud.kr/docs/api#agent-tool-test)

### 결제

- [크레딧/사용량](https://katcloud.kr/docs/api#payment)
- [크레딧 현황](https://katcloud.kr/docs/api#payment-summary)
- [사용/충전 이력](https://katcloud.kr/docs/api#payment-history)
- [그룹별 사용량](https://katcloud.kr/docs/api#payment-usage)

### 연동

- [웹훅](https://katcloud.kr/docs/api#webhook)
- [설정 관리](https://katcloud.kr/docs/api#webhook-config)
- [전송·다시 보내기](https://katcloud.kr/docs/api#webhook-delivery)
- [서명 검증](https://katcloud.kr/docs/api#webhook-signature)
- [이벤트 목록](https://katcloud.kr/docs/api#webhook-events)
- [INTAKE (접수 결과)](https://katcloud.kr/docs/api#webhook-intake)

### 참고

- [에러 처리](https://katcloud.kr/docs/api#errors)
- [AI 상담원 에러 코드](https://katcloud.kr/docs/api#errors-agent)
- [발송 결과 코드](https://katcloud.kr/docs/api#result-codes)
- [코드 예시](https://katcloud.kr/docs/api#examples)
