SIP로 기존 교환기 연결하기: 연동 준비 체크리스트

SIP로 기존 교환기(PBX)를 KAT Cloud에 연결하려면 연동 범위와 용량을 정하고, SIP 접속 정보를 받아 네트워크·보안을 점검한 뒤, 시험 통화와 API로 결과를 확인하는 순서로 진행합니다. KAT Cloud의 SIP 서버 주소, 포트, 전송 방식, 인증 정보 같은 접속 정보는 KAT Cloud 콘솔 또는 도입 문의로 안내받습니다. 이 글은 그 정보를 받기 전후에 준비할 항목을 단계별 체크리스트로 정리했습니다.

1단계: 범위·용량 정하고 계정 준비하기

연동을 시작하기 전에 다음을 먼저 정리합니다. 어떤 구조로 붙일지는 기존 PBX·콜센터에 AI 붙이기에서 비교했습니다.

• 연동 방향: 수신만 받을지, 발신도 할지 정합니다. 발신은 SIP로 연결한 PBX가 KAT Cloud 회선으로 거는 구조입니다.
• AI로 보낼 통화: 전체 통화, 업무 시간 외, 대기열 초과, IVR 특정 메뉴 가운데 어디까지인지 정합니다.
• 번호: 사용할 KAT Cloud 번호(그룹 채널) 개수와 기존 대표번호 유지 여부를 정합니다.
• 동시통화: 피크 시간 동시 통화 수를 추정합니다. KAT Cloud는 10회선이 기본이고 100회선 단위(월 100,000원, 부가세 별도)로 최대 1만회선까지 늘릴 수 있습니다.
• PBX 정보: 기종과 버전, SIP 트렁크 지원 여부, 트렁크 채널 라이선스 수를 확인합니다.
• 담당자: PBX 관리자, 네트워크·방화벽 관리자, 서비스 개발자를 정해 둡니다.

계정 쪽에서는 KAT Cloud에 가입해 그룹을 만들고(070 번호 자동 발급), 콘솔에서 API 키를 발급받습니다. 연동 검증에 쓸 그룹·웹훅·통화 기록 API는 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서 사용할 수 있고, 조건을 충족하지 않으면 403 AU017이 반환됩니다(사용 범위와 권한). 먼저 API 키와 그룹 정보를 확인합니다.

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

# 그룹 번호와 채널 ID 확인
curl -X GET "https://studio-gateway.zerocall.kr/group" \
  -H "x-api-key: $KAT_API_KEY"

import os
import requests

BASE_URL = "https://studio-gateway.zerocall.kr"
HEADERS = {
    "x-api-key": os.environ["KAT_API_KEY"],
    "Content-Type": "application/json",
}

def call_api(method, path, **kwargs):
    res = requests.request(method, f"{BASE_URL}{path}", headers=HEADERS, timeout=10, **kwargs)
    res.raise_for_status()
    body = res.json()
    # 성공 응답은 {"code": "0", "message": "Success", "result": ...} 구조입니다
    return body.get("result", body) if isinstance(body, dict) else body

print(call_api("GET", "/auth-check"))  # apiKeyId, userId, groupIdList
for group in call_api("GET", "/group"):
    print(group["id"], group["title"], group["phoneNumber"], group["channelId"], group["status"])

2단계: SIP 접속 정보 확보하기

PBX 트렁크 설정에 넣을 값은 모두 KAT Cloud 콘솔 또는 도입 문의로 안내받습니다. 다음 항목을 빠짐없이 받았는지 확인합니다.

3단계: 네트워크·보안 점검하기

• 방화벽: 안내받은 SIP 신호 주소·포트와 RTP 포트 범위를 양방향으로 허용하고, 가능하면 출발지를 안내받은 주소로 제한합니다.
• NAT: PBX가 사설망 안에 있다면 SIP 헤더와 SDP에 공인 주소가 적히도록 PBX의 외부 주소 설정을 맞춥니다. SBC가 있다면 SBC를 경계 지점으로 둡니다.
• SIP ALG: 공유기나 방화벽의 SIP ALG 기능이 SIP 메시지를 잘못 고쳐 단방향 음성이나 등록 실패를 일으키는 경우가 많으므로, 끄는 것을 먼저 검토합니다.
• 연결 유지: NAT 연결 정보가 만료되어 통화나 등록이 끊기지 않도록 OPTIONS 킵얼라이브나 재등록 주기를 설정합니다.
• 보안: TLS·SRTP를 쓸 수 있다면 적용하고, 트렁크 계정 비밀번호를 강하게 관리합니다. PBX에서 국제전화와 유료 번호 발신을 제한해 무단 발신 피해를 막습니다.

SIP 메시지가 어떤 순서로 오가는지 알고 있으면 문제를 훨씬 빨리 찾을 수 있습니다. 기본 흐름은 SIP 프로토콜 입문에 정리했습니다.

4단계: PBX 설정과 시험 통화

PBX에서는 트렁크 생성, 코덱 우선순위, DTMF 방식, 착신 경로(인바운드 라우트), 발신 경로(아웃바운드 라우트와 번호 변환, 발신번호) 순으로 설정한 뒤 다음 시험 통화를 진행합니다.

5단계: API로 통화 기록·웹훅 확인하기

시험 통화가 끝나면 KAT Cloud 쪽 기록으로 결과를 검증합니다. 먼저 통화 완료 이벤트를 받을 웹훅을 등록하고 테스트합니다. 웹훅 URL은 https만 쓸 수 있으며, 수신 서버는 10초 안에 2xx로 응답해야 합니다(웹훅 API).

# 통화 완료 웹훅 등록
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://example.com/webhook/call-completed"}'

# 등록한 웹훅으로 테스트 페이로드 전송 (응답의 success, statusCode, responseTime 확인)
curl -X POST "https://studio-gateway.zerocall.kr/webhook/1/test" \
  -H "x-api-key: $KAT_API_KEY"

# 시험 통화 후 통화 기록 조회
curl -X GET "https://studio-gateway.zerocall.kr/call-history?groupId=1&limit=20" \
  -H "x-api-key: $KAT_API_KEY"

GROUP_ID = 1  # GET /group 응답의 id

history = call_api("GET", "/call-history", params={"groupId": GROUP_ID, "limit": 20})
for call in history["data"]:
    print(
        call["createdAt"], call["fromNumber"], "->", call["toNumber"],
        "수신" if call["isInbound"] else "발신",
        call["status"], call["tag"], f'{call["duration"]}초',
    )

시험 통화마다 status가 ANSWERED인지, duration이 실제 통화 시간과 비슷한지, isInbound와 tag가 의도한 경로와 맞는지 확인합니다. 받아쓰기와 요약은 통화가 끝난 뒤 처리가 완료되어야 채워지고, isRecorded가 false인 통화에는 녹음·요약·받아쓰기가 없습니다(통화 기록 API). 웹훅 점검 방법은 웹훅 등록·수정·테스트에서, 운영 단계의 기록 수집은 통화 기록 증분 동기화에서 이어서 다룹니다.

증상별 점검표

증상이 해결되지 않으면 PBX의 SIP 로그(메시지 원문)와 시각, 발신·착신 번호를 함께 정리해 문의하면 원인을 빠르게 좁힐 수 있습니다.

자주 묻는 질문

KAT Cloud의 SIP 서버 주소와 포트는 어디서 확인하나요?

KAT Cloud의 SIP 서버 주소, 포트, 전송 방식, 인증 정보는 KAT Cloud 콘솔 또는 도입 문의로 안내받습니다. SIP 표준 기본 포트를 그대로 가정하지 말고 안내받은 값으로 PBX 트렁크를 설정해야 합니다.

SIP 직접 연결에 추가 비용이 있나요?

KAT Cloud의 SIP 직접 연결은 개인·비즈니스 모든 플랜에서 무료입니다. 통화 요금과 동시통화 회선 추가(100회선당 월 100,000원, 부가세 별도) 같은 사용량·부가서비스 요금은 요금표 기준으로 따로 계산합니다.

시험 통화가 연결은 되는데 소리가 한쪽만 들리면 무엇부터 보나요?

단방향 음성은 대부분 NAT나 방화벽 때문에 RTP 음성이 한쪽으로만 흐를 때 생깁니다. PBX가 SDP에 공인 주소를 적고 있는지, 안내받은 RTP 포트 범위가 방화벽에서 양방향으로 열려 있는지, 공유기의 SIP ALG가 켜져 있는지부터 확인합니다.