API 연동

내 API 연동

우리 회사의 REST API 를 AI 상담봇의 "도구" 로 등록합니다. 코드를 배포할 필요 없이 대시보드에서 스펙을 작성하고, 테스트하고, 연결하면 끝입니다.

#동작 방식

스펙에 등록한 작업(operation) 하나가 AI 가 쓸 수 있는 도구 하나가 됩니다. AI 는 작업의 설명을 읽고 대화 중 언제 어떤 도구를 쓸지 스스로 판단해, 필요한 값을 채워 호출합니다.

고객: "DM-10001 주문 어디쯤 왔어요? 번호 뒷자리 1234 예요"
AI → verify_customer(order_no, phone_last4) → 고객 확인
AI → get_order(order_no) — 고객 ID 는 본인확인 결과에서 자동으로 채움
AI: "CJ대한통운으로 배송 중이에요. [배송 조회하기](…)"

요청은 클립톡 서버가 보냅니다. 키는 서버에서만 쓰이고, AI 모델에는 응답 데이터만 전달됩니다.

POST https://www.mydomain.com/api/shop/verify
Authorization: Bearer ••••••
Content-Type: application/json

{ "order_no": "DM-10001", "phone_last4": "1234" }

→ 200
{ "ok": true, "customer": { "id": "cus_1001", "name": "김클립" } }

GET https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10001
Authorization: Bearer ••••••

→ 200
{ "ok": true, "order": { "status": "shipped", "status_label": "배송중", … } }

#시작하기

1
스튜디오 열기
프로젝트 → AI 상담봇 → 커넥터 내 API (직접 정의) → API 스펙 만들기.
2
템플릿 고르기
업종에 맞는 기본 커넥터를 고르면 프로젝트의 내 도메인 기준 주소(https://www.mydomain.com/api/…)로 스펙이 채워집니다. 스펙은 API 레퍼런스에 있습니다. 먼저 체험하려면 "데모 쇼핑몰" 샘플을, 처음부터 만들려면 빈 스펙을 고르세요.
3
저장
상단 저장. 보안키는 저장된 Base URL 에 묶이므로 먼저 저장해야 합니다.
4
보안키 입력
보안키 탭에서 키를 저장합니다. 데모는 데모 키 넣기 버튼을 누르세요.
5
테스트
API 테스트 탭에서 verify_customer → get_order 순서로 호출해 봅니다.
6
연결
저장 후 AI 상담봇에 연결. 위젯에서 "주문 조회해 주세요" 라고 말해 보세요.

#기본 설정

항목	설명
`Base URL`	모든 작업 경로 앞에 붙는 주소. https 필수, 공개 인터넷 주소만 가능. 예: https://api.example.com/v1
`인증 방식`	없음 / Bearer 토큰 / API 키 헤더 / Basic / 쿼리 파라미터. 키 값이 아니라 보안키 "이름" 을 고릅니다.
`추가 헤더`	모든 요청에 붙는 고정 헤더. 키가 필요하면 {{secrets.NAME}} 으로 참조.
`응답 제한 시간`	2~30초. 넘으면 실패로 처리하고 AI 가 고객에게 양해를 구합니다.
`본인확인 안내 문구`	첫 인사에 "(…알려주시면 시작됩니다)" 로 표시.
`할 수 있는 일`	첫 인사에 목록으로 보여줄 기능 설명.
`API 사용 규칙`	AI 에게 주는 추가 규칙 (예: 발송된 주문은 반품 안내).

{
  "name": "우리 쇼핑몰 API",
  "baseUrl": "https://api.example.com/v1",
  "timeoutMs": 12000,
  "auth": { "type": "header", "secret": "API_KEY", "headerName": "x-api-key" },
  "headers": [
    { "name": "X-Store-Id", "value": "store_77" },
    { "name": "X-Store-Token", "value": "{{secrets.STORE_TOKEN}}" }
  ],
  "verifyHint": "주문번호와 연락처 뒷 4자리를 알려주세요",
  "capabilities": ["주문·배송 조회", "배송 전 주문 취소"]
}

#작업 작성

항목	설명
`도구 이름`	영문 소문자·숫자·_ (예: get_order). 동사로 시작하면 AI 가 이해하기 쉽습니다.
`설명`	가장 중요합니다. 무엇을 돌려주는지, 언제 쓰는지, 전제 조건을 구체적으로 적습니다.
`메서드 · 경로`	GET/POST/PUT/PATCH/DELETE 와 Base URL 뒤 경로. {이름} 은 path 파라미터.
`유형`	조회: 바로 호출 · 본인확인: 고객 확인, 결과를 기억 · 처리: 고객 동의 후 실행
`결과 위치`	응답 중 AI 에게 넘길 부분 (예: data.orders). 비우면 전체.
`고객 정보 위치`	(본인확인) 성공 응답에서 고객 객체 위치. 기본 customer.
`미리보기(dry_run)`	(처리) 먼저 dry_run:true 로 호출해 결과를 고객에게 보여주고, 동의하면 dry_run:false 로 실행.

좋은 설명: "본인확인된 고객의 최근 주문 목록(주문번호·상품·금액·상태)을 최신순으로 조회한다. 배송 문의에 먼저 사용한다."
나쁜 설명: "주문 API"

작업은 5~15개 정도가 적당합니다. 비슷한 작업이 너무 많으면 AI 가 헷갈립니다.

#파라미터

파라미터는 위치(path · query · body · header)와 값 출처를 가집니다.

값 출처	설명	예
`AI 가 대화에서 채움`	고객이 말한 내용에서 AI 가 값을 뽑습니다. 설명·예시·허용값을 적으면 정확해집니다.	order_no, date
`본인확인 고객 정보`	본인확인 성공 응답의 고객 객체에서 가져옵니다. AI 가 임의로 바꿀 수 없어 안전합니다.	customer_id ← id
`고정값`	항상 같은 값.	limit = 10

body 파라미터 이름에 점을 쓰면 중첩 객체가 됩니다: address.zip → {"address":{"zip":"…"}}

고객 ID 처럼 "누구의 데이터인가" 를 정하는 값은 반드시 본인확인 고객 정보로 채우세요. AI 가 채우게 하면 다른 고객의 ID 를 넣으려는 시도를 막기 어렵습니다. API 서버에서도 소유권을 다시 검증하세요.

{
  "name": "get_order",
  "title": "주문 상세·배송 조회",
  "description": "주문 1건의 상세(상품, 결제 금액, 배송 상태, 운송장 번호)를 조회한다.",
  "method": "GET",
  "path": "/customers/{customer_id}/orders/{order_no}",
  "kind": "read",
  "params": [
    { "name": "customer_id", "in": "path", "type": "string",
      "required": true, "source": "customer", "value": "id" },
    { "name": "order_no", "in": "path", "type": "string",
      "required": true, "source": "model",
      "description": "주문번호", "example": "DM-10001" }
  ]
}

#본인확인

고객 정보를 다루려면 본인확인 유형 작업이 하나 필요합니다. 고객이 알려준 정보(주문번호 + 연락처 뒷자리, 예약번호 + 이름 등)를 API 로 보내고, 일치하면 고객 객체를 돌려주세요.

성공 응답의 고객 객체(기본 위치 customer)는 상담 동안 기억되고, "본인확인 고객 정보" 파라미터에 쓰입니다.
고객 객체는 짧게: id, name 정도. 비밀번호·토큰·카드 같은 필드는 자동으로 제외됩니다.
본인확인이 필요한 작업은 확인 전에 호출되지 않습니다(클립톡이 차단).
실패 시 { "ok": false, "message": "…" } 를 주면 AI 가 그 문장으로 다시 요청합니다.

// 성공
{ "ok": true, "customer": { "id": "cus_1001", "name": "김클립", "grade": "VIP" } }

// 실패 (HTTP 200 이어도 ok:false 면 실패로 처리)
{ "ok": false, "error": "not_found",
  "message": "주문번호와 휴대폰 뒷 4자리가 일치하는 고객을 찾지 못했습니다." }

#처리 작업과 고객 확인

처리 유형(취소·변경·신청)은 AI 가 호출해도 바로 실행되지 않습니다.

AI 가 처리 도구를 호출하면 클립톡이 제안을 만듭니다. 미리보기를 켰다면 이때 dry_run: true 로 API 를 호출해 결과를 받습니다.
고객에게 내용과 함께 네 아니오 버튼이 표시됩니다.
고객이 동의하면 같은 값으로 dry_run: false 호출 → 실제 처리. 결과는 상담 기록에 "AI 처리 기록" 메모로 남습니다.
30분이 지나면 제안은 만료됩니다.

미리보기 응답에 summary(문자열 배열)를 넣으면 확인 카드에 그대로 보입니다.

// POST …/orders/DM-10002/cancel  { "dry_run": true }
{
  "ok": true,
  "dry_run": true,
  "summary": [
    "주문번호: DM-10002",
    "상품: 무선 충전 패드 15W x2",
    "환불 예정 금액: 38,000원 (3~5영업일)"
  ]
}

// 고객 동의 후 { "dry_run": false }
{
  "ok": true,
  "status": "cancelled",
  "message": "주문 DM-10002 이(가) 취소되었습니다."
}

#보안키

API 키·토큰·비밀번호는 보안키 탭에서만 입력합니다.

입력 즉시 AES-256-GCM 으로 암호화되어 저장되고, 저장 후에는 누구에게도 다시 표시되지 않습니다(관리자 포함). 바꾸려면 같은 이름으로 새 값을 저장합니다.
AI 모델, 브라우저, 채팅 기록, 테스트 결과 어디에도 키 값은 나오지 않습니다. API 가 응답에 키를 되돌려 보내도 가려집니다.
키는 저장할 때의 Base URL 도메인으로만 전송됩니다. 스펙의 주소를 다른 도메인으로 바꾸면 키가 잠기고 다시 입력해야 합니다. (편집 권한이 있는 사람이 주소를 바꿔 키를 빼돌리는 것을 막습니다.)
스펙에서는 인증 설정의 보안키 이름이나 헤더 값의 {{secrets.NAME}} 으로만 참조합니다. 파라미터(쿼리·본문)에는 넣을 수 없습니다.

권장: 챗봇 전용 키를 새로 발급하고, 조회·필요한 처리만 가능한 최소 권한을 주세요. API 서버에서 클립톡 서버 IP 만 허용하면 더 안전합니다. 키 유출이 의심되면 발급처에서 폐기하고 새 키를 저장하세요.

// 인증 설정 — Authorization: Bearer <API_KEY 값>
"auth": { "type": "bearer", "secret": "API_KEY" }

// 추가 헤더에서 참조
"headers": [
  { "name": "X-Store-Token", "value": "{{secrets.STORE_TOKEN}}" }
]

// ✗ 이렇게 쓰지 마세요 (스펙에 평문으로 남음)
"headers": [{ "name": "x-api-key", "value": "sk_live_abc123" }]

#API 테스트

API 테스트 탭은 AI 가 대화 중에 호출하는 것과 똑같이 클립톡 서버에서 요청을 보냅니다. 저장 전 편집 내용으로도 테스트할 수 있습니다.

응답 — 상태 코드, 응답 시간, 크기, JSON 본문
AI 가 받는 결과 — 결과 위치·크기 제한을 적용한 뒤 AI 에게 전달되는 내용
보낸 요청 — 실제 URL·헤더·본문 (키는 가림)
해결 방법 — 401·404·타임아웃 등 실패 원인별 안내

본인확인 작업을 먼저 테스트하면 돌려받은 고객 정보가 테스트용 고객 정보에 자동으로 채워져, 이어서 고객 정보가 필요한 작업을 테스트할 수 있습니다. 처리 작업은 기본으로 dry_run 미리보기로 호출됩니다.

테스트는 프로젝트당 분당 30회로 제한됩니다.

#OpenAPI 가져오기

이미 OpenAPI 3 / Swagger 2 문서가 있다면 JSON · 가져오기 탭에 붙여넣어 작업을 한 번에 만들 수 있습니다. 경로·파라미터·JSON 요청 본문·인증 방식을 변환합니다(최대 30개).

가져온 뒤에는 꼭 다듬으세요: 필요 없는 작업 끄기, 설명을 "언제 쓰는지" 중심으로 고치기, 고객 ID 파라미터를 "본인확인 고객 정보" 로 바꾸기, GET 이 아닌 작업의 유형(처리/조회) 확인.

#제한과 규칙

항목	값
`작업 수`	최대 30개 (권장 5~15개)
`작업당 파라미터`	최대 25개
`보안키`	최대 10개
`요청 제한 시간`	2~30초 (기본 12초)
`응답 크기`	1MB 까지 읽음, AI 에게는 약 12,000자까지 전달
`주소`	https + 공개 인터넷 주소만. 사내망·localhost·클라우드 메타데이터 주소 차단, 리다이렉트는 따라가지 않음
`적용`	저장 후 최대 20초 뒤 새 대화부터