개요

Quickchat AI는 AI 에이전트 설정, 지식 베이스, 대화, AI Actions 등에 프로그램 방식으로 접근하는 REST API를 제공합니다.

선택적으로 사용할 수 있는 예시 검사

• 배포 방식 비교하기. 명시한 채널, 웹사이트 접근 권한, 필요한 기능을 Quickchat AI 설정 옵션과 비교합니다. 웹사이트나 계정을 검사하지는 않습니다.

• 예시 MCP 연결 검사하기. Cloudflare 문서 또는 Microsoft Learn 엔드포인트에서만 초기화하고 도구를 나열합니다. 로그인이나 도구 실행은 하지 않습니다.

인증

모든 API 엔드포인트는 Bearer 토큰 인증을 사용합니다. 모든 요청의 Authorization 헤더에 API 토큰을 포함하세요.

Authorization: Bearer <API_TOKEN>

토큰은 Quickchat 대시보드의 외부 앱 > API에서 만듭니다. 각 토큰은 scenario_id를 포함하는 JWT이므로 추가 식별자 헤더가 필요하지 않습니다.

• 토큰 유효 기간: 생성 후 52주
• 대시보드에서 언제든 토큰을 취소할 수 있습니다.
• 각 토큰은 AI 에이전트(시나리오) 하나에만 적용됩니다.
• 토큰을 만들려면 Business 플랜 이상가 필요합니다. 하위 요금제에서는 옵션이 비활성화되고 엔드포인트가 402 Payment Required를 반환합니다.

참고

실시간 Chat 엔드포인트(POST https://app.quickchat.ai/chat)는 같은 Bearer 토큰을 사용하지만 /v1/api/ 기본 경로 밖에 있으며 요청 본문에 scenario_id가 필요합니다. 전체 참조는 채팅 페이지를 확인하세요.

토큰 권한 범위

API 토큰은 두 가지 권한 범위 중 하나로 생성됩니다.

권한 범위	접근 수준	설명
read_all	읽기 전용	모든 리소스를 읽을 수 있지만 생성, 수정, 삭제는 불가
write_all	읽기 + 쓰기	쓰기를 포함한 모든 엔드포인트의 전체 접근 권한

• 대시보드 외부 앱 > API에서 생성할 때 권한 범위를 지정합니다.
• write_all은 모든 read_all 권한을 자동으로 포함합니다.
• 쓰기 엔드포인트에 read_all 토큰을 사용하면 403과 "Insufficient token scope. Required: write_all"을 반환합니다.

팁

모니터링, 분석, 읽기 전용 연동에는 read_all 토큰을 사용하세요. 리소스 생성이나 수정이 필요할 때만 write_all을 사용하세요.

엔드포인트 그룹별 필요한 권한:

엔드포인트 그룹	읽기 작업	쓰기 작업
챗봇 설정	read_all	write_all
지식 베이스 설정	read_all	write_all
문서	read_all	write_all
문서 언어별 URL	read_all	write_all
태그	read_all	없음
파일 업로드	없음	write_all
외부 콘텐츠 가져오기	없음	write_all
Intercom 지식 베이스	read_all	write_all
Widget 설정	read_all	write_all
대화	read_all	없음
대화 메타데이터	read_all	write_all
상담원 연결 설정	read_all	write_all
대화 평가	read_all	write_all
AI Actions	read_all	write_all

기본 URL

엔드포인트 그룹	기본 URL
지식 베이스, AI Actions, 파일 업로드, 가져오기, 챗봇 설정, Widget, 상담원 연결, 대화 평가	https://app.quickchat.ai/v1/api/
대화	https://app.quickchat.ai/v1/api_core/
실시간 채팅	https://app.quickchat.ai/chat

요청 제한

요청 제한은 토큰별, 엔드포인트별로 적용됩니다.

등급	한도	적용 대상
READ	분당 120회	GET 및 목록 조회
WRITE	분당 60회	POST, PATCH, PUT, DELETE
HEAVY	분당 20회	파일 업로드, 가져오기, 수집

요청 제한을 초과하면 HTTP 429 Too Many Requests를 반환합니다.

웹훅

Quickchat AI는 아웃바운드 웹훅을 보내지 않습니다. 이벤트를 구독하여 메시지 도착, 상담원 연결, 대화 종료 시 엔드포인트로 POST를 받는 방법은 없습니다.

사용 가능한 대안은 각각 목적이 다릅니다.

• AI Actions는 대화 중 API를 호출합니다. API Actions에는 AI가 결정, 첫 답변 전, 메타데이터가 일치할 때 모드가 있습니다. 자동 모드는 문서에 명시된 조건에서 대화당 한 번 호출을 시도하며 모든 메시지나 전달을 구독하지 않습니다. 리드 기록이나 필요한 데이터가 준비되었을 때 시스템에 알리는 작업 등에 사용하세요.
• Google Sheets는 Action 실행 시 행을 추가합니다. 모든 메시지나 전달을 자동 기록하지는 않습니다.
• Conversations API 폴링은 메시지와 기록된 전달 표시를 포함한 저장된 대화 및 이벤트를 조회합니다. 페이지 나누기와 위 READ 제한을 따르세요. 폴링에는 지연이 있으며 폴링 사이의 상태 비교로는 중간 변경을 놓칠 수 있습니다. 모든 전달이나 배정 전환의 완전한 기록이라고 가정하지 마세요.

API 접근에는 Business 요금제가 필요합니다. 요금제 및 한도를 참고하세요.

페이지 나누기

목록 엔드포인트는 쿼리 매개변수로 페이지를 나눕니다.

매개변수	설명
limit 정수	페이지당 항목 수
offset 정수	건너뛸 항목 수

페이지별 응답은 다음 구조를 따릅니다.

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

오류 처리

모든 오류는 다음 JSON 형식으로 반환됩니다.

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

상태	코드	설명
400	BAD_REQUEST	잘못된 입력 또는 필수 필드 누락
401	PERMISSION_DENIED	잘못되었거나 만료되거나 취소된 토큰
402	PAYMENT_REQUIRED	활성 구독 필요
403	PERMISSION_DENIED	작업에 필요한 토큰 권한 부족
404	NOT_FOUND	리소스를 찾을 수 없음
409	CONFLICT	충돌하는 작업(예: 동시 수정)
422	VALIDATION_ERROR	요청 본문 스키마 검증 실패
429	TOO_MANY_REQUESTS	요청 한도 초과
500	UNKNOWN	내부 서버 오류
503	SERVICE_UNAVAILABLE	일시적 이용 불가

---