채팅

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

• API Action 요청 미리보기. 요청을 보내지 않고 가상 예시 값으로 제공한 요청 템플릿을 렌더링합니다. 인증 헤더는 제외하세요.

• 메타데이터 키 미리보기. 중복 이름과 예약 키 오류를 포함하여 입력한 필드 이름이 변수 키가 되는 방식을 확인합니다. 값이나 계정별 권한은 검사하지 않습니다.

채팅

실시간 Chat 엔드포인트는 방문자 메시지를 AI 에이전트에 보내고 한 번의 왕복 요청으로 응답을 반환합니다. Quickchat AI 기반의 맞춤 채팅 UI를 만들 때 사용하세요.

다른 엔드포인트와 두 가지가 다릅니다. /v1/api/와 /v1/api_core/ 기본 경로 밖의 app.quickchat.ai/chat에 있으며 scenario_id를 토큰 대신 요청 본문에서 읽습니다. 인증은 다른 API와 같은 Bearer 토큰을 사용합니다.

참고

모든 요청을 https://app.quickchat.ai/chat으로 보내세요. 본문의 scenario_id는 Bearer 토큰이 연결된 AI 에이전트와 일치해야 합니다.

메시지 보내기

POST https://app.quickchat.ai/chat

요청 본문

매개변수	설명
scenario_id 문자열, 필수	AI 에이전트 ID. Bearer 토큰에 연결된 scenario_id와 일치해야 합니다.
text 문자열, 필수	사용자 입력 메시지
conv_id 문자열	대화 ID. 첫 요청에서 생략하면 새 대화를 시작합니다. 이후에는 반환된 conv_id를 보내 대화를 이어가세요.
client_metadata 객체	각 메시지에 첨부할 사용자 지정 키-값 쌍(최대 5개 키 권장). 받은편지함 대화 내보내기에 데이터 열로 표시됩니다.

conv_id 없는 요청은 새 대화를 시작하고 생성된 conv_id를 응답으로 반환합니다. 이 conv_id를 저장하고 후속 요청에 보내 여러 상호작용에 걸쳐 대화 맥락을 유지하세요.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

응답 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

필드	설명
conv_id 문자열	항상 반환되는 대화 식별자. 본문의 conv_id에 다시 보내 대화를 이어가세요.
reply 문자열	AI 에이전트 응답. <br> 줄바꿈 같은 HTML이 포함될 수 있습니다.
ord_number 정수	대화 내 순차 메시지 번호
src 정수	내부 소스 표시. API 클라이언트는 무시해도 됩니다.

기존 대화를 이어가려면 받은 conv_id를 다시 보내세요.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

클라이언트 메타데이터

Chat 엔드포인트의 선택적 client_metadata는 새 메시지마다 할당되고 받은편지함 대화 내보내기에 데이터 열로 표시되는 사용자 지정 속성입니다. Widget으로도 같은 속성을 첨부할 수 있습니다. {"userId": 12, "website": "mywebsite.com"}처럼 한 번에 최대 5개 키를 권장합니다. API가 강제하는 한도가 아닌 권장 사항입니다.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

지식 베이스 태그 필터링

지식 베이스 문서에 태그를 추가하여 AI가 참조할 문서를 제한하면 지식 베이스의 일부만으로 답하게 할 수 있습니다. 현재 이 필터는 API에서만 지원합니다.

태그로 필터링하려면 client_metadata에 kb_topic 키를 추가하세요. 대화를 시작하는 요청을 포함하여 모든 요청에 kb_topic이 있어야 합니다. 값은 요청마다 바꿀 수 있지만 필터를 적용하려면 대화 내내 키가 있어야 합니다.

아래 예시에서는 your-topic 태그가 있거나 태그가 없는 모든 문서를 응답 지식 후보에 포함합니다.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

오류

Chat 엔드포인트는 적절한 HTTP 상태 코드와 일반 텍스트 오류 메시지를 반환합니다.

상태	설명	조치
400	scenario_id 또는 인증 정보 누락	본문에 scenario_id를 넣고 유효한 Authorization: Bearer <API_TOKEN> 헤더를 포함하세요.
400	잘못된 conv_id(Conversation conv_id <id> is not valid.)	conv_id를 생략하여 새 대화를 시작하거나 이전 응답이 반환한 conv_id를 보내세요.
401	잘못된 인증 정보(Unauthorized.)	Bearer 토큰이나 API 키가 이 scenario_id에 유효한지 확인하세요.
404	알 수 없는 scenario_id(No implementation found for scenario_id <id>)	scenario_id와 Bearer 토큰이 해당 ID에 연결되었는지 확인하세요.
500	내부 서버 오류	서비스 쪽 문제입니다. 지원팀에 문의하세요.
503	서비스 이용 불가	서버 과부하 또는 유지보수 중입니다. 지속되면 지원팀에 문의하세요.