상담원 연결을 사용하면 AI 에이전트가 사람의 도움이 필요한 상황을 감지해 자동으로 대화를 전달합니다. 전달은 AI가 판단합니다. 설정 가능한 가이드라인에 따라 대화를 계속 평가하고 적절할 때 수동 개입 없이 실행합니다.
자동 전달 방식:
- 대화 중 AI가 각 메시지를 기본 가이드라인(사용자 불만, 지식 부족 등)과 직접 정의한 맞춤 가이드라인에 따라 평가합니다.
- 가이드라인이 충족되면 사람과 대화하고 싶은지 묻는 확인 메시지를 표시합니다.
- 방문자가 확인하면 상담원에게 전달하며 선택적으로 지금까지의 대화에 대한 AI 요약을 함께 제공합니다.
- 근무 시간을 설정했고 요청이 시간 밖에 들어오면 대신 사용자 지정 메시지를 표시합니다.
추가 전달 방법:
- 키워드 트리거: 방문자가 “사람과 대화”, “상담원” 같은 특정 문구로 직접 요청할 수 있습니다.
- 대시보드에서 수동 전달: 상담원이 받은편지함에서 담당자를 바꾸어 어떤 대화든 이어받을 수 있습니다.
주제 기반 라우팅은 팀원별 라우팅 설명을 바탕으로 AI가 한 명에게 전달하도록 합니다. 각 프로필은 사용자 한 명에 속하며 인사이트 주제 분류와 별개입니다. PUT 요청의 routing_profiles로 설정하세요. 담당자 배정과 이메일 알림 수신자는 별도 설정입니다.
선택적으로 사용할 수 있는 예시 검사
섹션 제목: “선택적으로 사용할 수 있는 예시 검사”-
API Action 요청 미리보기. 요청을 보내지 않고 가상 예시 값으로 제공한 요청 템플릿을 렌더링합니다. 인증 헤더는 제외하세요.
-
테스트 데이터셋 검증하기. 에이전트를 실행하지 않고 입력한 소규모 데이터셋이 지원 형식에 맞는지 확인합니다.
상담원 연결 설정 조회
섹션 제목: “상담원 연결 설정 조회”GET https://app.quickchat.ai/v1/api/human_handoff/configuration
curl https://app.quickchat.ai/v1/api/human_handoff/configuration \ -H 'Authorization: Bearer <API_TOKEN>'import requests
response = requests.get( url="https://app.quickchat.ai/v1/api/human_handoff/configuration", headers={"Authorization": "Bearer <API_TOKEN>"},)data = response.json()응답 200 OK
응답에는 여러 중첩 객체가 포함됩니다.
settings: 기본 전달 설정:
| 필드 | 설명 |
|---|---|
is_active 불리언 | 상담원 연결 활성화 여부 |
keywords 문자열 배열 | 전달을 요청하는 키워드(예: ["speak to human", "agent"]) |
ai_summary_active 불리언 | 전달 시 상담원에게 AI가 만든 대화 요약 발송 |
topic_based_routing_active 불리언 | 특정 상담원으로 주제 기반 라우팅 활성화 여부(읽기 전용, 라우팅 프로필로 설정) |
question_message 문자열 | 사람과 연결할지 묻는 방문자용 메시지 |
confirmation_message 문자열 | 방문자가 전달을 확인한 뒤 표시할 메시지(최대 500자) |
confirmation_outside_working_hours_message 문자열 | 근무 시간 외 전달 요청 시 표시할 메시지(최대 500자) |
working_hours_active 불리언 | 전달을 근무 시간으로 제한 |
timezone 문자열 | 근무 시간의 시간대(예: "Europe/London") |
send_email_notification 불리언 | 전달 시 상담원에게 이메일 알림 발송 |
emails 문자열 배열 | 알릴 이메일 주소 |
availability: 근무 시간 일정(시간 구간 배열):
| 필드 | 설명 |
|---|---|
id 정수 | 응대 가능 시간 구간 ID |
day_span 문자열 | 요일 또는 요일 범위(예: "monday", "monday-friday") |
start_time 문자열 | "HH:MM" 형식의 시작 시간 |
end_time 문자열 | "HH:MM" 형식의 종료 시간 |
generic_guidelines: 사전 정의된 전달 트리거 규칙(배열):
| 필드 | 설명 |
|---|---|
name 문자열 | 가이드라인 유형: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message" |
description 문자열 | 가이드라인이 실행되는 조건 설명 |
is_active 불리언 | 이 가이드라인 활성화 여부 |
custom_guidelines: 사용자 정의 전달 트리거 규칙(배열):
| 필드 | 설명 |
|---|---|
id 정수 | 가이드라인 ID |
name 문자열 | 맞춤 가이드라인 이름(최대 100자) |
description 문자열 | 전달을 실행해야 하는 조건(최대 2,000자) |
is_active 불리언 | 이 가이드라인 활성화 여부 |
routing_profiles: 주제 기반 라우팅은 대화 내용을 바탕으로 적절한 상담원에게 전달합니다.
AI가 전달을 시작하면 활성 라우팅 프로필 중 팀원을 선택할 수 있습니다. 유효한 선택이면 해당 사용자에게 배정하고, 아니면 미할당 상태로 둡니다. 다른 전달 트리거도 미할당 상태를 유지할 수 있습니다. 이메일 알림은 라우팅 선택과 독립적으로 settings.send_email_notification과 settings.emails를 사용합니다.
예시: 재무 담당자의 설명을 “결제 및 청구서 문의”, 엔지니어의 설명을 “기술 지원”으로 지정하세요. 청구서 문의에 대해 AI가 재무 담당자에게 배정할 수 있습니다. 이 배정으로 이메일 수신자 목록이 바뀌지는 않습니다.
Actions 및 MCPs > 상담원 연결 > Action 편집 > 주제 기반 라우팅 또는 PUT 요청으로 프로필을 설정하세요.
| 필드 | 설명 |
|---|---|
user_id 정수 | 팀원의 사용자 ID. 해당 에이전트에 접근할 수 있어야 합니다. |
routing_description 문자열 | 팀원이 처리할 대화 설명(최대 150자, 활성화 시 비어 있을 수 없음) |
is_active 불리언 | 이 라우팅 프로필 활성화 여부 |
email, first_name, last_name 문자열 | GET이 반환하는 사용자 정보. PUT에서는 필요하지 않음 |
상담원 연결 설정 수정
섹션 제목: “상담원 연결 설정 수정”PUT https://app.quickchat.ai/v1/api/human_handoff/configuration
PUT은 전달 설정 전체를 원자적으로 교체합니다. settings, availability, generic_guidelines, custom_guidelines를 포함하세요. 라우팅을 유지하려면 routing_profiles도 포함해야 합니다. 생략하면 기본값인 빈 목록이 적용되어 기존 프로필을 제거합니다. 일부만 바꾸려면 먼저 GET으로 현재 설정을 조회하고 필요한 필드를 수정한 뒤 전체 객체를 PUT으로 보내세요. 각 프로필은 user_id, routing_description, is_active를 사용합니다.
# First, fetch the current configurationCONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \ -H 'Authorization: Bearer <API_TOKEN>')
# Modify and PUT back (example: enable handoff)echo "$CONFIG" | jq '.settings.is_active = true' | \curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \ -H 'Authorization: Bearer <API_TOKEN>' \ -H 'Content-Type: application/json' \ -d @-import requests
headers = {"Authorization": "Bearer <API_TOKEN>"}
# Fetch current configurationconfig = requests.get( url="https://app.quickchat.ai/v1/api/human_handoff/configuration", headers=headers,).json()
# Modify and PUT backconfig["settings"]["is_active"] = True
response = requests.put( url="https://app.quickchat.ai/v1/api/human_handoff/configuration", headers=headers, json=config,)data = response.json()응답 200 OK: 수정된 전달 설정을 반환합니다.