전화 예약·주문 접수 자동화: 기록형 매뉴얼(NOTE)과 INTAKE 웹훅
KAT Cloud AI 상담원에 기록형 매뉴얼(NOTE)을 붙이면 예약·주문처럼 정해진 칸을 손님께 물어 받아 적고, 저장·변경·취소할 때마다 통화 중에 INTAKE 웹훅으로 보냅니다. 칸 설계와 requestType 처리법을 코드로 정리했습니다.

KAT Cloud AI 상담원으로 전화 예약이나 주문을 받으려면 상담원에 기록형 매뉴얼(manualKind: "NOTE")을 등록해 받아 적을 칸을 정하고, INTAKE 웹훅을 등록하면 됩니다. 상담원은 칸마다 손님께 묻고 되읽어 확인한 뒤 저장하며, 저장·변경·취소할 때마다 통화가 끝나기 전에 INTAKE 알림이 내 서버로 옵니다. 내 서버는 intakeId를 기준으로 접수를 덮어쓰고, requestType으로 새 접수·변경·취소를 나누면 됩니다.
기록형 매뉴얼과 안내용 매뉴얼의 차이
상담원 전용 매뉴얼은 두 종류입니다. 안내용(GENERAL)은 상담원이 필요할 때 꺼내 읽는 응대 지침이고, 기록형(NOTE)은 정해진 칸을 손님께 물어 받아 적는 접수 양식입니다. 상담원 하나에 매뉴얼은 30개까지 둘 수 있습니다(매뉴얼 문서).
| 구분 | GENERAL(안내) | NOTE(기록형) |
|---|---|---|
| 용도 | 환불 규정, 주차 안내 같은 지침 | 예약·주문·방문 접수 |
| 결과물 | 상담원의 답변 | 칸별 값과 접수 내용 |
| 내 서버로 오는 것 | 통화 기록·요약 | INTAKE 웹훅(통화 중), CALL_COMPLETED의 intakes |
상담원을 아직 만들지 않았다면 AI 상담원 만들기를 먼저 보세요.
1단계: 받아 적을 칸 설계하기
칸은 noteFields에 20개까지 정합니다. 각 칸의 key는 웹훅에서 값을 읽는 이름이고, type이 상담원이 받는 값의 형식을 정합니다.
| type | 받는 값 | 설계 요령 |
|---|---|---|
TEXT | 자유 글 | 이름, 요청 사항 |
NUMBER | 숫자 | 인원, 수량 |
BOOLEAN | 예/아니오 | 주차 필요 여부 |
DATE | YYYY-MM-DD | 지난 날짜·없는 날짜는 접수하지 않고 되물음 |
TIME | HH:mm(24시간) | 방문·픽업 시간 |
PHONE | 0으로 시작하는 9~11자리 | 비우면 지금 전화한 번호를 씀 |
ENUM | options 중 하나 | 좌석, 메뉴처럼 선택지가 정해진 값 |
칸이 많을수록 통화가 길어집니다. 꼭 필요한 칸만 required: true(기본값)로 두고, 나머지는 required: false로 두세요.
curl -X POST "https://studio-gateway.zerocall.kr/group/1/agent/7/manual" \
-H "x-api-key: $KAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "포장 주문",
"description": "손님이 포장 주문, 주문 변경, 주문 취소를 원할 때",
"content": "포장은 30분 뒤부터 받습니다. 한 번에 10개가 넘으면 담당자 확인으로 안내합니다.",
"manualKind": "NOTE",
"noteFields": [
{ "key": "menu", "label": "메뉴", "type": "ENUM", "options": ["불고기", "제육", "비빔밥"] },
{ "key": "qty", "label": "수량", "type": "NUMBER" },
{ "key": "pickupTime", "label": "픽업 시간", "type": "TIME" },
{ "key": "phone", "label": "연락처", "type": "PHONE", "required": false }
]
}'description은 상담원이 어떤 매뉴얼을 꺼낼지 고르는 기준이므로 "언제 쓰는지"를 구체적으로 적습니다. 접수 뒤 담당자에게 연결하려면 noteHandoffEnabled: true를 켭니다. 이 설정은 그룹의 담당자 연결이 켜져 있을 때만 실제로 연결합니다.
2단계: INTAKE 웹훅 등록하기
POST /webhook에 eventType: "INTAKE"와 https 주소를 넣어 등록합니다. 통화가 끝난 뒤에만 결과가 필요하다면 CALL_COMPLETED의 intakes 배열로도 받을 수 있지만, 주방 화면이나 예약 장부에 바로 띄우려면 INTAKE가 맞습니다. 알림 본문 필드는 INTAKE 문서에 있습니다.
3단계: requestType별로 처리하기
접수 진행 규칙은 이렇습니다. 같은 통화에서 손님이 내용을 바꾸거나 취소하면 새로 쌓지 않고 같은 intakeId로 다시 알림이 옵니다. 같은 통화에 앞 접수가 없는데 CHANGE·CANCEL이 오면 "지난 접수의 변경·취소 요청"이라는 뜻입니다.
// 서명 검증과 eventId 중복 거르기를 통과한 뒤 부르는 함수
async function handleIntake(data, db) {
const known = await db.intakes.findById(data.intakeId);
if (!known && data.requestType !== 'NEW') {
// 이 통화에서 처음 보는 접수의 변경·취소 = 지난 예약에 대한 요청
await db.followUps.insert({
intakeId: data.intakeId,
type: data.requestType, // CHANGE 또는 CANCEL
phone: data.customerPhoneNumber,
content: data.content,
});
return; // 기존 예약을 찾아 바꾸는 일은 직원이 확인 후 처리
}
// NEW, 또는 같은 통화 안의 변경·취소 → intakeId 기준으로 덮어쓰기
await db.intakes.upsert({
intakeId: data.intakeId,
callHistoryId: data.callHistoryId,
status: data.requestType === 'CANCEL' ? 'CANCELED' : 'ACTIVE',
fields: data.fields, // { menu, qty, pickupTime, phone } — 못 받은 칸은 null
content: data.content, // 사람이 읽는 접수 내용(날짜에 요일이 붙음)
updatedAt: data.updatedAt,
});
}중복 거르기는 eventId로, 저장은 intakeId로 합니다. 같은 접수가 바뀌면 intakeId는 같고 eventId는 새 값이기 때문입니다. 서명 검증과 중복 거르기 코드는 웹훅 서명 검증에서 다룹니다.
운영할 때 챙길 점
- 확정과 접수를 구분합니다. 상담원은 접수한 내용을 기록할 뿐, 자리가 실제로 있는지는 모릅니다. 자리 확인이 필요하면 HTTP 도구로 예약 시스템을 조회하게 하거나(HTTP·MCP 도구 붙이기), 매장이 확정한 뒤 문자로 알립니다.
- 지난 예약 변경은 사람이 봅니다. 위 코드처럼 따로 쌓아 두고 직원이 확인합니다.
- 결과는 통화 기록과 맞춰 봅니다.
callHistoryId로 통화 기록 API의 받아쓰기를 찾아, 칸 값이 대화와 맞는지 표본 검사합니다.
KAT Cloud 가입하기로 시작하거나, 접수 양식 설계가 고민된다면 도입 상담을 신청하세요. 식당 업무 전체 흐름은 식당 예약 전화 AI 에이전트에서 볼 수 있습니다.
자주 묻는 질문
INTAKE 웹훅은 통화가 끝난 뒤에 오나요?
KAT Cloud의 INTAKE 웹훅은 AI 상담원이 기록형 접수를 저장·변경·취소할 때마다 통화 중에 바로 전송됩니다. 통화가 끝난 뒤의 최종 상태는 CALL_COMPLETED 웹훅의 intakes 배열에도 담깁니다.
손님이 통화 중에 예약 시간을 바꾸면 접수가 두 건이 되나요?
KAT Cloud AI 상담원은 같은 통화에서 접수를 바꾸거나 취소하면 새로 쌓지 않고 앞 접수를 고칩니다. 그래서 INTAKE 알림은 같은 intakeId에 requestType CHANGE 또는 CANCEL로 오며, 내 서버는 intakeId 기준으로 덮어쓰면 됩니다.
기록형 매뉴얼로 받으면 안 되는 정보가 있나요?
KAT Cloud AI 상담원은 지시와 상관없이 카드번호·비밀번호·인증번호·주민등록번호를 받지 않습니다. 이런 값을 받는 칸은 만들지 말고, 결제는 문자로 보내는 결제 링크처럼 별도 경로로 처리하세요.
- #AI 상담원
- #기록형 매뉴얼
- #INTAKE 웹훅
- #전화 예약
- #주문 접수



