Quickstart
5분 빠른 시작
API 키를 받고, 번호를 만들고, 전화와 문자를 보내고, 웹훅으로 결과를 받습니다. 예시는 모두 복사해서 바로 쓸 수 있습니다. Base URL 은 https://studio-gateway.zerocall.kr 입니다.
02
번호 받기
가입하면 070 번호가 하나 생깁니다. 이 번호로 전화와 문자를 주고받습니다. GET /group 으로 그룹 ID, 번호(phoneNumber), 채널 ID(channelId)를 확인합니다. 다음 단계에서 씁니다.
번호가 더 필요하면 유료 요금제에서 POST /group/{groupId}/numbers 로 하나씩 더 받습니다. 늘어날 월 요금은 GET /group/{groupId}/numbers/quote 로 먼저 봅니다.
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 "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"04
문자 보내기
고객 번호로 채팅방을 열고 메시지를 보냅니다. 같은 번호면 기존 채팅방 ID 가 돌아옵니다. 길이와 첨부에 따라 SMS · LMS · MMS 가 자동으로 정해집니다.
응답의 chatId 는 발송 결과 웹훅 SEND_RESULT 의 data.chatId 와 같습니다.
# 채팅방 열기 → 채팅방 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 -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 "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- 01계정 만들기
- 02전화번호 발급
- 03에이전트 연결하고 첫 통화
