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

Quickstart

5분 빠른 시작

API 키를 받고, 번호를 만들고, 전화와 문자를 보내고, 웹훅으로 결과를 받습니다. 예시는 모두 복사해서 바로 쓸 수 있습니다. Base URL 은 https://studio-gateway.zerocall.kr 입니다.

01

가입하고 API 키 받기

콘솔에 가입하고 API 키를 발급받습니다. 키는 x-api-key 헤더에 그대로 넣습니다. 키가 맞는지는 GET /auth-check 로 확인합니다.

예시는 키를 환경 변수 KAT_API_KEY 에 넣었다고 보고 씁니다. 키는 코드에 적지 마세요.

cURL
export KAT_API_KEY="발급받은 API 키"

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

자세히인증사용 범위와 권한

02

번호 받기

가입하면 070 번호가 하나 생깁니다. 이 번호로 전화와 문자를 주고받습니다. GET /group 으로 그룹 ID, 번호(phoneNumber), 채널 ID(channelId)를 확인합니다. 다음 단계에서 씁니다.

번호가 더 필요하면 유료 요금제에서 POST /group/{groupId}/numbers 로 하나씩 더 받습니다. 늘어날 월 요금은 GET /group/{groupId}/numbers/quote 로 먼저 봅니다.

cURL
curl "https://studio-gateway.zerocall.kr/group" \
  -H "x-api-key: $KAT_API_KEY"

# 번호 하나 더 받기 (유료 요금제, 월 요금이 늘어납니다)
curl "https://studio-gateway.zerocall.kr/group/$GROUP_ID/numbers/quote" \
  -H "x-api-key: $KAT_API_KEY"

curl -X POST "https://studio-gateway.zerocall.kr/group/$GROUP_ID/numbers" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Idempotency-Key: number-0001" \
  -H "Content-Type: application/json" \
  -d '{ "confirmMonthlyFee": true }'

자세히그룹 목록 조회번호 추가

03

전화 걸기

AI 발신은 발신 상담원(방향 OUTBOUND)이 대신 전화를 겁니다. 요청마다 Idempotency-Key 를 붙입니다. 재시도할 때는 같은 값을 보내야 전화가 두 번 걸리지 않습니다.

접수되면 바로 requestId 가 옵니다. 통화 결과는 조회하거나 웹훅 AI_OUTBOUND 로 받습니다. 요청 본문은 발신 상담원에 등록한 입력 칸을 따릅니다. 실제 전화가 걸리고 요금이 생깁니다.

cURL
# 발신 상담원 목록
curl "https://studio-gateway.zerocall.kr/group/$GROUP_ID/agent?direction=OUTBOUND" \
  -H "x-api-key: $KAT_API_KEY"

# 발신 접수 (call.json 은 상담원 입력 칸에 맞춰 작성)
curl -X POST "https://studio-gateway.zerocall.kr/group/$GROUP_ID/ai-outbound/calls" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @call.json

# 상태 조회
curl "https://studio-gateway.zerocall.kr/group/$GROUP_ID/ai-outbound/calls/$REQUEST_ID" \
  -H "x-api-key: $KAT_API_KEY"

자세히AI 발신 도구 · REST 대응표AI 상담원

04

문자 보내기

고객 번호로 채팅방을 열고 메시지를 보냅니다. 같은 번호면 기존 채팅방 ID 가 돌아옵니다. 길이와 첨부에 따라 SMS · LMS · MMS 가 자동으로 정해집니다.

응답의 chatId 는 발송 결과 웹훅 SEND_RESULT 의 data.chatId 와 같습니다.

cURL
# 채팅방 열기 → 채팅방 ID
curl -X POST "https://studio-gateway.zerocall.kr/chat-room" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": 100, "phoneNumber": "01098765432" }'

# 메시지 보내기
curl -X POST "https://studio-gateway.zerocall.kr/chat" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatRoomId": "채팅방 ID", "content": "예약 확인되었습니다." }'

자세히채팅방 생성메시지 발송

05

웹훅 받기

이벤트 하나에 받을 주소 하나를 등록합니다. 통화가 끝나면 CALL_COMPLETED 로 요약과 대화 내용이 옵니다. 주소는 https 여야 합니다.

등록한 뒤 POST /webhook/{webhookId}/test 로 시험 알림을 보내 봅니다. 시험 알림 본문에는 "isTest": true 가 들어갑니다.

cURL
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://my.app/kat/webhook" }'

# 시험 알림 보내기
curl -X POST "https://studio-gateway.zerocall.kr/webhook/$WEBHOOK_ID/test" \
  -H "x-api-key: $KAT_API_KEY"

자세히웹훅 설정웹훅 이벤트 목록

06

서명 검증

모든 알림에 X-Webhook-Timestamp 와 X-Webhook-Signature 헤더가 붙습니다. 서명은 v1=HMAC-SHA256(비밀값, "<timestamp>.<본문 원문>") 의 16진수입니다.

비밀값은 GET /webhook/secret 으로 받습니다. 본문은 파싱하기 전 바이트 그대로 검증합니다.

cURL
curl "https://studio-gateway.zerocall.kr/webhook/secret" \
  -H "x-api-key: $KAT_API_KEY"
# → { "secret": "whsec_…" }

# 서명 직접 계산해 보기 (본문을 body.json 에 저장했을 때)
printf '%s.' "$TIMESTAMP" | cat - body.json \
  | openssl dgst -sha256 -hmac "$KAT_WEBHOOK_SECRET" -hex

자세히Node · Python 검증 코드서명 검증

—

다음 단계

  • AI 에이전트에서 바로 쓰려면 MCP 서버를 연결합니다.
  • 받을 수 있는 이벤트와 재시도 규칙은 웹훅 문서에 있습니다.
  • 문자 발신 외 API 는 비즈니스 요금제 그룹이나 별도 허용된 그룹에서 씁니다. 사용 범위와 권한을 확인하세요.
  • 에러 코드는 에러 처리에 정리돼 있습니다.

Get started

오늘 만든 AI에게
전화번호 연결

가입 후 7일 동안 개인 플랜을 무료로 쓸 수 있습니다. 번호를 발급하고 첫 전화를 받아보세요.

이미 계정이 있나요? 로그인

  1. 01계정 만들기
  2. 02전화번호 발급
  3. 03에이전트 연결하고 첫 통화