KAT Cloud 시작하기: 가입부터 첫 번호 발급과 웹훅 등록까지

KAT Cloud(캣클라우드)를 시작하는 순서는 가입, API 키 발급, 인증 확인, 그룹 생성(전화번호 발급), 웹훅 등록의 다섯 단계입니다. KAT Cloud는 가입하면 1주일(7일) 무료 체험이 열리고, 모든 API는 https://studio-gateway.zerocall.kr 주소에 x-api-key 헤더를 붙여 호출합니다. 이 글은 각 단계를 cURL과 Python 코드로 그대로 따라 할 수 있게 정리했습니다.

시작 전에 알아 둘 개념과 사용 범위

KAT Cloud API를 쓰기 전에 리소스 관계를 먼저 잡아 두면 이후 단계가 쉬워집니다. API 키는 사용자 단위로 발급되고, 실제 전화 업무는 그룹 단위로 돌아갑니다.

API 종류마다 사용 조건이 다릅니다. 문자 발신 API(POST /message/send, GET /message/send-result/{chatId}, POST /message/media/upload)는 모든 사용자가 쓸 수 있습니다. 그룹, 전화번호 풀, 통화 기록, 크레딧, 웹훅 같은 그 밖의 API는 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서만 쓸 수 있습니다. 자세한 조건은 API 문서의 사용 범위에 있습니다.

따라 하려면 아래 세 가지를 준비합니다.

• curl을 실행할 수 있는 터미널
• Python 3와 requests 패키지(pip install requests)
• 웹훅을 받을 https 주소(4단계에서 씁니다. 아직 없다면 나중에 등록해도 됩니다)

1단계: 가입하고 콘솔에서 API 키 발급받기

katcloud.kr에서 가입하면 1주일 무료 체험이 바로 시작됩니다. 체험은 개인 플랜 그대로 제공되며, 개인 플랜의 포함량과 요금은 요금표에서 확인할 수 있습니다. 모든 금액은 부가세 별도입니다.

API 키는 KAT Cloud 콘솔에서 발급합니다. 발급받은 키는 전체 문자열을 그대로 x-api-key 헤더에 넣어 씁니다. 앞뒤를 자르거나 Bearer 같은 접두어를 붙이지 않습니다. 키는 코드에 직접 적지 말고 환경 변수로 넘깁니다.

export KAT_API_KEY="콘솔에서 발급받은 키 전체 문자열"

API 키는 반드시 서버에서만 사용합니다. 브라우저나 모바일 앱 코드, 공개 저장소에 키가 들어가면 누구나 내 계정으로 API를 호출할 수 있습니다. 키 보관 방법과 사용 범위는 API 키 발급과 인증 확인 글에서 더 자세히 다룹니다.

2단계: /auth-check로 인증 확인하기

GET /auth-check는 API 키가 유효한지 확인하는 엔드포인트입니다. 다른 API를 부르기 전에 한 번 호출해 키가 제대로 들어갔는지 봅니다.

curl -X GET "https://studio-gateway.zerocall.kr/auth-check" \
  -H "x-api-key: $KAT_API_KEY"

{
  "code": "0",
  "message": "Success",
  "result": {
    "apiKeyId": 123,
    "userId": 456,
    "name": "My API Key",
    "groupIdList": [1, 2, 3]
  }
}

apiKeyId는 키 ID, userId는 사용자 ID, name은 키 이름, groupIdList는 이 키에 연결된 그룹 ID 목록입니다. KAT Cloud의 성공 응답은 code, message, result 구조를 쓰고, API 문서의 엔드포인트별 예시는 가독성을 위해 result 값만 보여 줄 수 있습니다. 그래서 아래 Python 예제는 result가 있으면 꺼내고, 없으면 본문을 그대로 돌려주는 함수를 하나 둡니다. 이후 단계도 이 함수를 그대로 씁니다.

import os
import requests

BASE_URL = "https://studio-gateway.zerocall.kr"

session = requests.Session()
session.headers.update({
    "x-api-key": os.environ["KAT_API_KEY"],
    "Content-Type": "application/json",
})


def call(method, path, **kwargs):
    resp = session.request(method, BASE_URL + path, timeout=10, **kwargs)
    if not resp.ok:
        # 에러 형식: {"status": 401, "code": "AU002", "message": "..."}
        raise RuntimeError(f"{resp.status_code} {resp.text}")
    if not resp.content:
        return None  # 204 No Content
    body = resp.json()
    # 공통 성공 응답 {"code": "0", "message": "Success", "result": ...}
    if isinstance(body, dict) and "result" in body:
        return body["result"]
    return body


me = call("GET", "/auth-check")
print("키 이름:", me["name"], "/ 연결된 그룹:", me["groupIdList"])

401 응답이 오면 키 문자열이 잘렸거나, 헤더 이름이 x-api-key가 아니거나, 환경 변수가 비어 있을 가능성이 큽니다. 에러 본문은 {"status": 401, "code": "AU002", "message": "올바르지 않은 토큰입니다."} 형식으로 옵니다.

3단계: 그룹을 만들어 전화번호 발급받기

그룹을 만들면 전화번호(채널)가 자동으로 발급됩니다. POST /group의 요청 필드는 모두 선택입니다.

curl -X POST "https://studio-gateway.zerocall.kr/group" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groupTitle": "첫 번째 서비스"}'

성공하면 result에 새 그룹 ID(예: 123)가 숫자로 들어옵니다. 발급된 번호와 채널 ID는 GET /group으로 확인합니다.

group_id = call("POST", "/group", json={"groupTitle": "첫 번째 서비스"})

groups = call("GET", "/group")
mine = next(g for g in groups if g["id"] == group_id)
print(mine["phoneNumber"], mine["channelId"], mine["status"])

GET /group 응답의 각 항목에는 id, title, phoneNumber, channelId, status(ACTIVE, INACTIVE, PENDING), recordingEnabled(통화 녹음 활성화 여부), createdAt이 들어 있습니다. channelId는 이후 채팅방을 만들 때 쓰므로 함께 저장해 둡니다.

plan 값은 요금 청구와 API 사용 범위에 함께 영향을 줍니다. 어떤 값으로 그룹을 만들지는 요금표를 보고 정한 뒤 지정하세요. 번호를 미리 확인하는 방법, 그룹 삭제와 번호 반납은 그룹 만들고 070 번호 발급받기에서 이어서 설명합니다.

4단계: 웹훅 등록하고 테스트 보내기

웹훅은 이벤트가 생기면 KAT Cloud가 등록된 URL로 HTTP POST를 보내는 방식입니다. POST /webhook에 eventType과 url(https)을 보내 등록합니다. 이벤트는 네 가지입니다.

처음에는 통화 결과를 받는 CALL_COMPLETED 하나만 등록해 봅니다.

curl -X POST "https://studio-gateway.zerocall.kr/webhook" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"eventType": "CALL_COMPLETED", "url": "https://api.example.com/webhooks/katcloud"}'

응답에는 웹훅 id, eventType, url, createdAt, updatedAt이 들어 있습니다. 이 id로 테스트 페이로드를 보내 수신 서버가 응답하는지 확인합니다.

hook = call("POST", "/webhook", json={
    "eventType": "CALL_COMPLETED",
    "url": "https://api.example.com/webhooks/katcloud",
})

test = call("POST", f"/webhook/{hook['id']}/test")
print(test["success"], test["statusCode"], test["responseTime"], test["error"])

테스트 결과의 success가 true이고 statusCode가 2xx면 연결이 된 것입니다. KAT Cloud 문서가 권장하는 웹훅 처리 기준은 타임아웃 10초, HTTP 2xx 응답 시 성공 처리, 비동기 처리 후 즉시 응답입니다. 실패할 때 어디를 봐야 하는지는 웹훅 등록·수정·테스트에 정리했습니다.

5단계: 첫 통화로 전체 흐름 확인하기

AI 에이전트의 응대 지침과 음성 모델 선택은 KAT Cloud 콘솔에서 설정합니다. 설정을 마쳤다면 휴대폰으로 3단계에서 받은 번호에 전화를 걸어 봅니다.

통화가 끝나고 STT·요약 분석이 완료되면 CALL_COMPLETED 웹훅이 옵니다. 페이로드의 data에는 callHistoryId, status, tag, duration, summary, sttAI, sttDirect 등이 들어 있습니다. 웹훅 서버가 아직 없다면 통화 기록 API로 직접 확인해도 됩니다.

curl -X GET "https://studio-gateway.zerocall.kr/call-history?groupId=123&offset=0&limit=20" \
  -H "x-api-key: $KAT_API_KEY"

통화 기록의 isRecorded가 false면 녹음 파일, 요약, STT 대화 내역이 제공되지 않습니다. 이때는 GET /group의 recordingEnabled 값을 먼저 확인합니다.

지금까지의 단계를 표로 정리하면 다음과 같습니다.

포함량을 넘겨도 통화는 끊기지 않고, 초과분은 누적 구간 단가로 청구됩니다. 실제 사용량으로 한 달 요금을 미리 계산하는 방법은 KAT Cloud 요금 계산 가이드를 참고하세요. 엔드포인트 전체 목록은 KAT Cloud API 문서에 있습니다.

자주 묻는 질문

KAT Cloud 무료 체험은 어떻게 시작하나요?

KAT Cloud는 katcloud.kr에서 가입하면 1주일(7일) 무료 체험이 시작됩니다. 체험은 개인 플랜 그대로 제공되며, 개인 플랜의 포함량과 월 요금은 요금표에서 확인할 수 있습니다.

API를 호출했더니 403 AU017이 나옵니다. 왜 그런가요?

KAT Cloud API의 403 AU017은 문자 발신 외 API를 비즈니스 요금제가 아니거나 별도 허용되지 않은 그룹에 쓰려 할 때 반환됩니다. 경로에 groupId가 없는 요청은 API 키에 연결된 모든 그룹을 검사하므로, 비즈니스 기능용 키에는 조건을 충족하는 그룹만 연결하는 것이 권장됩니다.

웹훅 없이도 통화 결과를 확인할 수 있나요?

KAT Cloud는 GET /call-history로 그룹의 통화 기록을 조회할 수 있고, updatedAfter 파라미터로 마지막 조회 이후 갱신된 기록만 가져올 수도 있습니다. 다만 통화가 끝난 시점을 바로 알아야 한다면 API 문서는 CALL_COMPLETED 웹훅을 권장합니다.