유사 사이트를 조심하세요. 한국에이아이통신(주)의 공식 사이트는 katel.kr · katcloud.kr · zerocall.kr · aicallpay.com 입니다.공식 채널 확인
KAT CloudKOEN로그인

KAT Cloud AI 상담원 만들기: 지시·참고 정보·음성 설정과 번호 연결 API

KAT Cloud AI 상담원은 POST /group/{groupId}/agent로 지시와 참고 정보를 정해 만들고, PUT /group/{groupId}/agent/{agentId}/channel로 전화번호에 연결하면 그 번호로 오는 전화를 받습니다. 사용 조건과 필드, 연결 규칙을 정리했습니다.

가이드한국에이아이통신(주) KAT Cloud 팀6분 읽기
KAT Cloud AI 상담원 만들기: 지시·참고 정보·음성 설정과 번호 연결 API

KAT Cloud에서 AI 상담원을 만들려면 POST /group/{groupId}/agent로 상담원의 지시(prompt)와 참고 정보(context), 첫 인사와 음성 설정을 등록한 뒤, PUT /group/{groupId}/agent/{agentId}/channel로 그룹의 전화번호에 연결하면 됩니다. 연결한 번호로 걸려 온 전화는 그 상담원이 받습니다. 받는 전화용(INBOUND) 상담원과 함께, 거는 전화용(OUTBOUND) 상담원으로 전화를 거는 AI 상담원 발신도 제공합니다.

시작 전에: 사용 조건 두 가지

AI 상담원 API는 아무 그룹에서나 열리지 않습니다. 사용 범위 문서 기준으로 두 조건이 모두 필요합니다.

  1. 1비즈니스 기능 조건: 비즈니스 요금제 그룹이거나 별도 허용된 그룹이어야 합니다. 아니면 403 AU017이 반환됩니다.
  2. 2AI 상담원 기능: 그룹에 AI 상담원 기능이 켜져 있어야 합니다. 꺼져 있으면 403 AG002가 반환되며, 쓰려면 KAT Cloud에 신청합니다.

경로의 groupId는 API Key에 연결된 그룹이어야 하고(아니면 403 PK004), 그룹 하나에 상담원은 20개까지 만들 수 있습니다(AG009). 그룹과 번호를 아직 만들지 않았다면 그룹 만들고 070 번호 발급받기부터 진행하세요.

1단계: 상담원 등록하기

Shell
curl -X POST "https://studio-gateway.zerocall.kr/group/1/agent" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "치과 예약 상담원",
    "direction": "INBOUND",
    "prompt": "당신은 OO치과 예약 상담원입니다. 예약 문의와 진료 시간 안내를 맡습니다. 진단이나 비용 확답은 하지 않고 담당자 확인으로 안내합니다. 존댓말로 짧게 답합니다.",
    "context": "진료 시간 평일 10:00~19:00, 토요일 10:00~14:00, 일요일 휴진. 주차 2시간 무료.",
    "greeting": "안녕하세요, {지점명} AI 상담원입니다. 무엇을 도와드릴까요?",
    "voice": "HIGH_FEMALE",
    "language": "KO",
    "maxCallSeconds": 300
  }'

필드는 상담원 등록 문서 기준으로 이렇게 나뉩니다.

필드필수쓰는 법
name필수상담원 이름(100자 이하)
direction필수INBOUND 또는 OUTBOUND. 만든 뒤 바꿀 수 없음
prompt필수역할·목표·말투·금지 사항(8,000자 이하)
context선택회사·상품 같은 배경 정보(8,000자 이하)
greeting선택받는 전화의 첫 인사. 적은 문장을 그대로 말함(600자 이하), {지점명}은 그룹 이름으로 바뀜
voice선택HIGH_FEMALE·LOW_FEMALE·HIGH_MALE·LOW_MALE
language선택KO·EN·JA·ZH·TH
maxCallSeconds선택최대 통화 시간 30~480초, 비우면 480
aiInterruptionEnabled선택손님이 말하면 상담원이 말을 멈추는 끼어들기

prompt에는 "무엇을 하고 무엇을 하지 않는지"를, context에는 바뀔 수 있는 사실(영업시간, 가격, 주소)을 나눠 적으면 수정할 때 실수가 줄어듭니다. 업무별로 길어지는 응대 절차는 상담원 전용 매뉴얼로 빼는 편이 낫습니다(기록형 매뉴얼로 예약 접수 받기).

음성 모델은 어떻게 정하나

liveModel 필드로 음성 모델을 지정할 수 있지만, API에서는 지금 gemini-3.8-live만 고를 수 있습니다. 비워 두면 그룹에 정한 모델이나 기본 모델을 씁니다. KAT Cloud의 음성 모델 14종 중 다른 모델로 운영하려면 콘솔이나 도입 상담에서 확인하세요. 모델별 분당 요금과 고르는 기준은 음성 AI 모델 고르는 법과 요금에 정리되어 있습니다.

바꿀 수 없는 규칙과 함께 지시 쓰기

모든 상담원에는 지시와 상관없이 늘 지키는 규칙이 적용됩니다. AI라는 사실을 숨기지 않고, 카드번호·비밀번호·인증번호·주민등록번호는 받지 않으며, 날짜·시간·인원·이름·번호는 되읽어 확인합니다. 기록하지 않은 일을 처리했다고 말하지 않고, 손님이 끝내자고 할 때만 통화를 끝내며, 최대 통화 시간 30초 전에 마무리합니다.

그러니 지시에 "사람인 척하세요"나 "카드번호를 받아 적으세요"처럼 규칙과 부딪히는 내용을 넣으면 안 됩니다. 결제가 필요하면 그룹 문자 기능이 켜진 경우 상담원이 지시·참고 정보에 적힌 결제 링크를 문자로 보내게 할 수 있습니다.

2단계: 전화번호에 연결하기

그룹의 번호 목록은 GET /group/{groupId}/channel로 확인합니다. 응답의 id가 채널 ID입니다. 연결은 목록을 통째로 바꾸는 방식입니다.

Shell
curl -X PUT "https://studio-gateway.zerocall.kr/group/1/agent/7/channel" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channelIdList": [100]}'

번호 연결 문서의 규칙은 다음과 같습니다.

  • 같은 그룹의 번호만 연결할 수 있습니다(AG006).
  • 번호 하나에는 받는 전화용 상담원 하나만 연결됩니다(409 AG008). 꺼 둔 상담원도 세므로 먼저 다른 상담원의 연결을 끊어야 합니다.
  • 활성 상담원이 연결되지 않은 번호를 기본 AI가 대신 받지는 않습니다. 직원 착신 넘김이 설정되어 있으면 그 번호로 연결을 시도하고, 아니면 안내 후 종료합니다.
  • 빈 배열([])을 보내면 연결이 모두 끊깁니다.

3단계: 시험 통화와 수정 이력 확인

연결한 번호로 직접 전화를 걸어 첫 인사와 답변을 들어 봅니다. 통화가 끝나면 CALL_COMPLETED 웹훅과 통화 기록에 agentId·agentVersion이 남습니다. 지시를 고칠 때는 PATCH /group/{groupId}/agent/{agentId}로 바꿀 필드만 보내면 되고, 버전이 오르며 GET .../revision에서 버전별 내용을 확인할 수 있습니다. 어떤 버전의 지시로 통화했는지 맞춰 보면 고친 효과를 비교하기 쉽습니다.

KAT Cloud 가입하기로 7일 무료 체험을 시작하거나, AI 상담원 기능 신청과 구성이 필요하다면 도입 상담을 신청하세요. 전체 기능은 기능 목록에서 볼 수 있습니다.

자주 묻는 질문

AI 상담원 API를 호출했더니 403 AG002가 나옵니다.

KAT Cloud는 그룹에 AI 상담원 기능이 켜져 있지 않으면 AI 상담원 API에 403 AG002를 반환합니다. 비즈니스 기능 조건(비즈니스 요금제 또는 별도 허용 그룹)을 갖춘 뒤 KAT Cloud에 AI 상담원 기능을 신청하면 사용할 수 있습니다.

AI 상담원으로 전화를 걸 수도 있나요?

KAT Cloud는 받는 전화용(INBOUND) 상담원과 거는 전화용(OUTBOUND) 상담원을 모두 통화에 씁니다. 거는 전화용 상담원으로는 POST /group/{groupId}/ai-outbound/calls나 MCP create_ai_outbound_call로 전화를 걸고, 결과는 AI_OUTBOUND 웹훅으로 받습니다.

번호 하나에 상담원 두 개를 연결할 수 있나요?

KAT Cloud에서는 번호 하나에 받는 전화용 상담원 하나만 연결됩니다. 이미 다른 상담원이 연결된 번호에 연결하면 409 AG008이 반환되므로, 기존 연결을 끊고 다시 연결해야 합니다. 꺼 둔 상담원도 연결된 것으로 셉니다.

  • #AI 상담원
  • #음성 에이전트
  • #KAT Cloud API
  • #번호 연결
  • #프롬프트

Get started

만든 AI에 전화번호 연결

070 번호 발급, SIP 직접 연결, 음성 AI 모델 연결, 문자·웹훅까지 API 하나로. 월 10,000원부터.