그룹 만들고 070 번호 발급받기: POST /group과 번호 풀 조회

KAT Cloud에서 전화번호를 받는 방법은 그룹을 만드는 것입니다. POST /group으로 그룹을 생성하면 전화번호(채널)가 자동으로 발급되고, 기본은 070 번호입니다. 발급 가능 여부는 GET /phone-number-pool/available로 미리 확인하고, 발급된 번호는 GET /group으로 조회하며, 더 쓰지 않는 그룹은 DELETE /group/{groupId}로 삭제해 번호를 반납합니다.

그룹, 채널, 전화번호의 관계

KAT Cloud(캣클라우드)의 그룹은 서비스 운영 단위입니다. 매장, 지점, 프로젝트처럼 전화 업무를 나누는 단위를 그룹으로 만들고, 요금제와 사용량도 그룹 단위로 관리됩니다. 채널은 그룹에 연결된 전화번호이며, 이 번호로 전화와 문자를 주고받습니다. 한 그룹에 여러 채널을 추가할 수도 있습니다.

그룹에는 멤버도 있습니다. 그룹 멤버는 역할(관리자, 일반)에 따라 권한이 다르고, AI가 통화를 직원에게 넘길 때 그 통화를 받을 수 있습니다. 즉 그룹은 번호와 요금뿐 아니라 사람까지 묶는 단위입니다. 070 번호 자체가 어떤 번호인지는 070 번호란?에서 따로 설명합니다.

그룹 관련 API는 모두 비즈니스 기능 API입니다. 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서만 쓸 수 있고, 조건을 충족하지 못하면 403 AU017이 반환됩니다. 상세 조건은 API 문서의 사용 범위를 참고하세요.

발급 가능한 번호 확인: GET /phone-number-pool/available

GET /phone-number-pool/available은 지금 발급 가능한 번호가 있는지 확인하는 엔드포인트입니다.

curl -X GET "https://studio-gateway.zerocall.kr/phone-number-pool/available" \
  -H "x-api-key: $KAT_API_KEY"

{
  "code": "0",
  "message": "Success",
  "result": {
    "isAvailable": true,
    "phoneNumber": "07012345678"
  }
}

이 API는 번호 목록을 검색하는 기능이 아니라 샘플 번호 1개를 돌려줍니다. 그룹을 대량으로 만들기 전에 isAvailable이 true인지 먼저 보거나, 반환된 샘플 번호를 그대로 POST /group의 phoneNumber에 넣어 그 번호로 그룹을 만들 때 씁니다. 조회와 생성 사이에 다른 요청이 같은 번호를 가져갈 수 있으므로, 번호를 지정한 생성이 실패하면 샘플을 다시 받아 재시도하거나 phoneNumber 없이 랜덤 발급으로 바꿉니다.

POST /group으로 그룹 만들고 번호 받기

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으로 확인합니다.

Python으로는 아래처럼 묶을 수 있습니다. call 함수는 공통 성공 응답(code, message, result)에서 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:
        raise RuntimeError(f"{resp.status_code} {resp.text}")
    if not resp.content:
        return None
    body = resp.json()
    return body["result"] if isinstance(body, dict) and "result" in body else body


pool = call("GET", "/phone-number-pool/available")
if not pool["isAvailable"]:
    raise SystemExit("지금은 발급 가능한 번호가 없습니다.")

payload = {"groupTitle": "강남점"}
# 샘플 번호로 만들고 싶을 때만 지정합니다. 빼면 랜덤 발급입니다.
payload["phoneNumber"] = pool["phoneNumber"]

group_id = call("POST", "/group", json=payload)
print("새 그룹 ID:", group_id)

같은 요청을 재시도할 때는 주의가 필요합니다. 응답을 못 받았다고 바로 다시 보내면 그룹이 두 개 생길 수 있습니다. 재시도 전에 GET /group으로 같은 title의 그룹이 이미 생겼는지 확인하는 습관을 들이면 좋습니다.

GET /group으로 번호와 상태 확인하기

GET /group은 API 키로 접근 가능한 그룹 목록을 돌려줍니다.

[
  {
    "id": 1,
    "title": "매장A",
    "phoneNumber": "07012345678",
    "channelId": 100,
    "status": "ACTIVE",
    "recordingEnabled": true,
    "createdAt": "2026-01-15T09:00:00.000Z"
  }
]

새 그룹의 status가 ACTIVE가 아니라면 바로 운영에 투입하지 말고 잠시 뒤 다시 확인합니다.

import time


def wait_until_active(group_id, timeout=60):
    deadline = time.time() + timeout
    while time.time() < deadline:
        group = next((g for g in call("GET", "/group") if g["id"] == group_id), None)
        if group and group["status"] == "ACTIVE":
            return group
        time.sleep(3)
    raise TimeoutError(f"그룹 {group_id} 상태가 아직 ACTIVE가 아닙니다.")


group = wait_until_active(group_id)
print(group["phoneNumber"], group["channelId"], group["recordingEnabled"])

recordingEnabled가 false인 그룹의 통화는 녹음 파일, 요약, STT 대화 내역이 남지 않습니다. 통화 요약을 쓸 계획이라면 이 값을 먼저 확인합니다.

DELETE /group으로 그룹 삭제와 번호 반납

DELETE /group/{groupId}는 그룹을 삭제하고 전화번호를 반납합니다. 성공하면 본문 없이 204 No Content가 반환됩니다.

curl -i -X DELETE "https://studio-gateway.zerocall.kr/group/123" \
  -H "x-api-key: $KAT_API_KEY"

삭제 전에 아래 항목을 점검합니다.

• 이 번호로 걸려 오는 전화와 문자가 더는 없는지(홈페이지, 명함, 안내 문자 속 번호 교체)
• 보관해야 할 통화 기록과 녹음을 먼저 내려받았는지(통화 녹음 파일 내려받기 참고)
• 코드나 설정에 이 groupId, channelId가 남아 있지 않은지

그룹을 나누는 기준과 번호 비용

그룹을 어떻게 나눌지는 운영 방식에 따라 정합니다. 매장마다 번호와 사용량을 따로 보고 싶다면 매장별 그룹이 맞고, 하나의 서비스가 번호만 여러 개 필요하다면 한 그룹에 채널을 늘리는 쪽이 단순할 수 있습니다. 매장별 운영 예시는 프랜차이즈 다매장 전화 운영에 정리했습니다.

비용도 함께 봐야 합니다. 그룹을 만들 때마다 번호가 하나씩 발급되고, 번호 요금은 계정 전체 순번으로 매겨집니다. 플랜에 포함된 1개가 1번째입니다.

요금제와 사용량이 그룹 단위로 관리된다는 점도 기억해 둡니다. 그룹 구성에 따른 월 비용은 KAT Cloud 요금 계산 가이드의 계산식으로 미리 따져 볼 수 있습니다. 그룹 API 원문은 API 문서의 그룹 관리와 전화번호 풀에 있습니다.

자주 묻는 질문

KAT Cloud에서 그룹을 만들면 전화번호가 바로 발급되나요?

KAT Cloud는 POST /group으로 그룹을 만들면 전화번호(채널)를 자동으로 발급하며, 기본은 070 번호입니다. 생성 응답에는 그룹 ID만 들어 있으므로 번호, 채널 ID, 상태는 GET /group으로 확인합니다.

원하는 번호를 골라서 받을 수 있나요?

KAT Cloud의 POST /group은 phoneNumber 필드로 특정 번호를 지정할 수 있고, 비워 두면 랜덤으로 발급합니다. GET /phone-number-pool/available은 발급 가능 여부와 샘플 번호 1개만 돌려주므로, 번호를 검색해 고르는 기능으로 쓰지는 않습니다.

그룹을 삭제하면 번호는 어떻게 되나요?

KAT Cloud에서 DELETE /group/{groupId}로 그룹을 삭제하면 그 그룹의 전화번호가 반납되고, 성공 시 204 No Content가 반환됩니다. 반납한 번호를 다시 받을 수 있다는 보장은 문서에 없으므로 고객에게 안내된 번호라면 삭제 전에 신중히 확인해야 합니다.