API 연결
외부 API를 enuchat에 연결하여 AI 및 규칙이 시스템에서 실시간 데이터를 가져올 수 있도록 하세요.
작동 방식
API 연결을 사용하면 enuchat을 자체 백엔드 시스템 — 예약 엔진, CRM, 주문 관리, 재고 등 — 과 통합할 수 있습니다. 방문자가 질문을 하면 enuchat이 API를 호출하여 실제 데이터를 가져와 응답에 포함할 수 있습니다.
흐름
- 연결 구성 — API의 기본 URL 및 인증
- 엔드포인트 추가 — 경로 템플릿 및 응답 매핑이 있는 특정 API 호출
- 규칙 만들기 — CALL_API 작업이 있는 AI 또는 정적 규칙
- 방문자가 질문 — 규칙이 트리거되고, API를 호출하고, 응답을 세션 변수에 매핑
- AI가 실제 데이터로 응답 — 세션 변수는 정확한 답변 생성을 위해 AI에서 사용 가능
예: 호텔 객실 가용성
방문자: „다음 주에 205호실이 가능한가요?"
AI 규칙 일치: „방문자가 객실 가용성에 대해 물어볼 때"
CALL_API 작업: GET https://api.hotel.com/rooms/205/availability
응답 매핑됨: room_available = true, price = „120유로/박"
AI 응답: „205호실은 다음 주에 1박 120유로에 이용 가능합니다. 예약하시겠습니까?"
연결 설정
대시보드에서 설정 → API 연결로 이동하세요.
1. 연결 만들기
연결은 하나의 외부 API를 나타냅니다. 필요한 것:
| 필드 | 설명 | 예 |
|---|---|---|
| 이름 | 이 연결의 레이블 | 호텔 예약 API |
| 기본 URL | API의 루트 URL | https://api.hotel.com/v1 |
| 인증 유형 | 인증 방법 | Bearer Token, OAuth2 등. |
2. 인증 유형
없음
인증이 필요 없는 공개 API용.
API 키
헤더 또는 쿼리 매개변수로 정적 키를 보냅니다.
| 필드 | 설명 |
|---|---|
| 키 | API 키 값 |
| 헤더 이름 | 사용할 헤더 (기본: X-Api-Key) |
키는 다음과 같이 전송됩니다: X-Api-Key: your_key_here
Bearer Token
Authorization 헤더에 정적 토큰을 보냅니다.
다음과 같이 전송됨: Authorization: Bearer your_token_here
Basic Auth
base64로 인코딩된 사용자 이름과 비밀번호를 보냅니다.
다음과 같이 전송됨: Authorization: Basic dXNlcjpwYXNz
OAuth 2.0 (Client Credentials)
액세스 토큰을 자동으로 가져와 만료까지 캐시합니다. Salesforce, Google 또는 사용자 정의 OAuth 서버와 같은 최신 API에 가장 적합합니다.
| 필드 | 설명 |
|---|---|
| 토큰 URL | OAuth 토큰 엔드포인트 (예: https://auth.example.com/oauth/token) |
| 클라이언트 ID | OAuth 클라이언트 ID |
| 클라이언트 비밀번호 | OAuth 클라이언트 비밀번호 |
| 범위 | 공백으로 구분된 범위 (예: read write) |
enuchat은 토큰 수명 주기를 자동으로 처리합니다 — 첫 번째 호출에서 가져오고, 만료까지 캐시하고, 필요할 때 새로 고칩니다.
보안: 모든 자격 증명은 libsodium을 사용하여 저장 시 암호화됩니다. API 응답에 노출되지 않습니다 — 마스킹된 값만 대시보드에 표시됩니다.
엔드포인트 구성
각 연결에는 여러 엔드포인트가 있을 수 있습니다 — 수행하려는 특정 API 호출.
| 필드 | 설명 | 예 |
|---|---|---|
| 이름 | 이 엔드포인트의 레이블 | 가용성 확인 |
| 메서드 | HTTP 메서드 | GET, POST, PUT, DELETE |
| 경로 | URL 경로 (기본 URL에 추가됨). 동적 값에 대해 {'{'}variable} 사용 | /rooms/{'{'}roomId}/availability |
| 쿼리 매개변수 | 키-값 쌍으로 URL 매개변수. 값은 {'{'}variable} 지원 | date={'{'}checkIn} |
| 본문 템플릿 | POST/PUT의 JSON 본문. {'{'}variable} 보간 지원 | {'{'}"guest": "{'{'}name}"} |
| 응답 매핑 | 점 표기법을 사용하여 JSON 응답 필드를 세션 변수에 매핑 | data.available → room_available |
| 설명 | AI용 컨텍스트 (이 엔드포인트가 반환하는 데이터) | 객실 가용성 및 가격 반환 |
변수 보간
경로, 쿼리 매개변수 및 본문 템플릿에서 {'{'}variableName}를 사용하세요. 변수는 다음에서 옵니다:
- 세션 변수 — 이전 규칙에 의해 설정됨 (SET_VARIABLE 작업)
- 작업 매개변수 — CALL_API 규칙 작업에 하드코딩됨
응답 매핑
점 표기법을 사용하여 JSON 응답 필드를 세션 변수에 매핑:
// API가 반환:
{'{'}
"data": {'{'}
"available": true,
"price": {'{'} "amount": 120, "currency": "EUR" }
}
}
// 매핑:
data.available → room_available // "true"
data.price.amount → room_price // "120"
data.price.currency → room_currency // "EUR"매핑된 변수는 대화에 세션 변수로 저장되며 응답 생성을 위해 AI에서 사용할 수 있습니다.
규칙과 함께 사용
API 호출은 규칙의 CALL_API 작업에 의해 트리거됩니다. 다른 작업과 결합할 수 있습니다.
레시피: 주문 상태 조회
연결: 주문 관리 API — https://api.shop.com/v2 — Bearer Token
엔드포인트: GET /orders/{'{'}orderId} → data.status → order_status, data.eta → delivery_eta 매핑
규칙 (AI 유형): „방문자가 주문 상태나 배송에 대해 물어볼 때"
작업:
- CALL_API → 주문 상태 엔드포인트
- REPLY_AI → AI가
order_status및delivery_eta를 사용하여 응답
결과: 방문자: „내 주문 #4521은 어디 있나요?" — AI: „주문 #4521은 현재 배송 중이며 목요일까지 도착할 예정입니다."
레시피: 실시간 가격
연결: 가격 API — https://pricing.example.com — API 키
엔드포인트: GET /products/{'{'}productId}/price → price → current_price, currency → price_currency 매핑
규칙 (정적): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i
작업:
- CALL_API → 가격 엔드포인트
- REPLY_TEXT → „현재 가격은 {'{'}current_price} {'{'}price_currency}입니다."
테스트
규칙에 사용하기 전에 항상 연결 및 엔드포인트를 테스트하세요:
- 연결 테스트 — 인증이 작동하는지 확인 (OAuth2: 토큰 가져오기)
- 엔드포인트 테스트 — 샘플 변수로 실제 API 호출을 수행하고 응답 표시
- 규칙 테스트 (드라이 런) — 규칙 페이지에서 규칙이 일치하고 어떤 작업이 실행되는지 테스트
팁: 연결 테스트부터 시작하여 각 엔드포인트, 그 다음 전체 규칙을 테스트하세요. 이렇게 하면 각 수준에서 문제를 격리할 수 있습니다.
보안
- 저장 시 암호화 — 모든 자격 증명은 저장 전에 libsodium을 사용하여 암호화됨
- 절대 노출되지 않음 — API 응답에는 해독된 자격 증명이 포함되지 않고 마스킹된 값만 포함됨
- SSRF 보호 — enuchat은 localhost, 개인 IP 및 내부 호스트 이름에 대한 호출을 차단
- 타임아웃 — 외부 API 호출은 중단을 방지하기 위해 5초 타임아웃을 가짐
- OAuth2 토큰 캐싱 — 액세스 토큰은 안전하게 캐시되고 자동으로 새로 고쳐짐
- 테넌트 격리 — 연결은 테넌트 범위이며 다른 사람에게 액세스할 수 없음