어드밴스드 AI 상담사를 위한 데이터 내보내기 API 사용하기

사용 중인 플랜

Add-on

AI agents - Advanced

데이터 내보내기 API는 대화 데이터를 내보내고 다양한 플랫폼과 애플리케이션에 연동할 수 있어 AI 상담사의 잠재력을 최대한 활용하기 위한 핵심 역할을 합니다.

개발자, 비즈니스 분석가 또는 IT 전문가인지에 관계없이 API는 소중한 인사이트와 대화 메타데이터를 추출할 수 있는 안전하고 간소화된 솔루션을 제공하여 혁신을 주도하고, 정보에 입각한 의사결정을 하며, 조직을 새로운 차원으로 끌어올릴 수 있게 합니다.

이 문서에서는 다음과 같은 주제를 다룹니다.

• 조직 ID 얻기
• API 토큰 생성
• API에 대한 정보
• 파일 스키마
• 응답 예시
• 인기 메트릭
• 자주 묻는 질문(FAQ)

조직 ID 얻기

관리자 역할이 있는 사용자만 이 단계를 수행할 수 있습니다.

1. 왼쪽 사이드바에서 조직 관리를 클릭합니다.
   참고: 2024년 10월 7일 전에 AI 상담사 - 어드밴스드를 구매한 경우에는 대신 사용자 관리 > 조직 관리를 클릭합니다.
2. 조직을 클릭하여 조직의 프로필을 엽니다.
3. 브라우저의 URL에서 조직 ID를 찾습니다.

   https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s

API 토큰 생성

관리자 역할이 있는 사용자만 토큰을 생성할 수 있습니다.

1. 왼쪽 사이드바에서 조직 관리를 클릭합니다.
   참고: 2024년 10월 7일 전에 AI 상담사 - 어드밴스드를 구매한 경우에는 대신 사용자 관리 > 조직 관리를 클릭합니다.
2. 조직을 클릭하여 조직의 프로필을 엽니다.
3. API 키 탭을 선택합니다.
4. 생성을 클릭합니다.
5. 저장을 클릭합니다.
6. 키를 복사하여 안전하게 보관합니다.

조직 관리 페이지에서 나간 후에는 토큰에 액세스할 수 없게 됩니다. 이전에 생성한 토큰을 분실한 경우 다시 생성 버튼을 클릭하여 취소하면 됩니다. 이전 토큰의 유효성이 취소되고 새로 생성된 토큰을 사용할 수 있습니다.

API에 대한 정보

데이터 내보내기 API는 매일 자정(협정 세계시)에 한 번 업데이트됩니다. 이 업데이트 프로세스는 한동안 실행될 수 있으므로 이른 아침에 가져오기를 실행하면 데이터를 모두 확보하는 데 도움이 됩니다.

EU의 경우: POST - https://api.ultimate.ai/data-export/v3/get-signed-urls

미국의 경우: POST - https://api.us.ultimate.ai/data-export/v3/get-signed-urls

헤더

이름	필수	유형
botId	true	string
organizationId	true	string
authorization	true	string

본문

이름	필수	유형
date	true	ISO date string

응답

HTTP 코드	응답
200	{ "date": "string", "urls": [ "string" ] }
401	권한 없음
500	내부 서버 오류

참고:

• 파일의 URL은 요청 날짜로부터 하루 후에 만료됩니다. 유효한 링크를 얻기 위해 API 호출이 다시 한번 수행될 수 있습니다.
• 2024년 1월 1일까지 뒤로 돌아가 데이터를 요청할 수 있습니다. 이보다 더 오래된 데이터가 필요하면 Zendesk 고객 지원팀에 문의하여 도움을 받을 수 있습니다.

파일 스키마

API의 출력은 여기 설명된 구조를 따르며 해당 날의 모든 대화가 포함된 JSON 문서입니다.

• 파일은 JSON 개체의 목록이며 각 개체는 대화입니다.
• 파일의 이름 규약은 conversation_bot-id_date_000000000000.json입니다.

특성	설명	유형
"bot_id"	봇의 고유 ID	"bot_id": { "type": "string" },
"bot_name"	봇의 이름	"bot_name": { "type": "string" },
"conversation_id"	생성된 대화 ID	"conversation_id": { "type": "string" },
"platform_conversation_id"	CRM 특정 ID	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	대화가 시작된 날짜와 시간(UTC 시간대)	"conversation_start_time": { "type": "string" },
"conversation_end_time"	대화가 종료된 날짜와 시간(UTC 시간대)	"conversation_end_time": { "type": "string" },
"conversation_type"	대화에서 식별된 답장 유형 가능한 값에는 사용 사례, 지식. 하이브리드 및 기타가 포함됩니다.	"conversation_type": { "type": "string" },
"language"	대화의 언어	"language": { "type": "string" },
"channel"	대화의 채널 메시징 또는 이메일	"channel": { "type": "string" },
"labels"	대화와 연결된 모든 레이블 목록	"labels": { "type": "array", "items": { "type": "string" } },
"segments"	대화에서 식별된 모든 세그먼트 목록. 세그먼트에 대해 자세히 알아보세요.	"segments": { "type": "array", "items": { "type": "string" } },
"conversations_data"	세션 매개변수가 대화와 연결됩니다. 값이 있는 매개변수의 키 목록입니다. 정의되지 않은 키는 이 목록에 없습니다. 참고: 문자열로 저장되어 있더라도 “conversations_data”에는 또 다른 JSON 개체가 포함되어 있습니다. 대화 데이터 개체에서 BSAT(봇 만족도) 점수가 제공됩니다. BSAT(봇 만족도) 점수 값 -1 = 사용자에게 BSAT가 제공되었지만 응답을 남기지 않음 NULL = 사용자에게 BSAT가 제공되지 않았음 예: "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	대화가 테스트 대화인지 여부를 식별하는 플래그	"test_mode": { "type": "boolean" },
"conversation_status"	대화의 해결 예: bot_handled	"conversation_status": { "type": "string" },
"automated_resolution"	대화 평가의 결과가 자동 해결. 자동 해결 계산 방식에 대해 자세히 알아보세요.	"automated_resolutions": { "type": "string" },
"automated_resolution_reasoning"	대화가 자동으로 해결된 것으로 표시된 이유를 판단하는 데 사용되는 근거	"automated_resolution_reasoning": { "type": "string" },
"last_resolution"	대화의 최종 해결. 알림, 해결됨, 에스컬레이션됨 또는 정의되지 않음일 수 있습니다. 2026년 2월 28일에 이 기능이 제거됩니다. 예정된 기능 제거에 대해 자세히 알아보세요.	"last_resolution": { "type": "string" },
"triggered_replies"	답장과 관련된 세부 정보. reply_id, language, reply_name, reply_type, intent_id와 같은 정보가 포함됩니다.	"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_procedures"	procedure_id, intent_id, use_case_name과 같은 정보가 포함됩니다.  제로 학습 AI 상담사에 대해서나 트리거된 절차가 없을 때에는 이 섹션이 비어 있습니다.	"triggered_procedures": { "type": "array", "items": { "type": "string" } },
"triggered_use_cases"	사용 사례가 다이얼로그 또는 절차로 구성되었는지 식별하는 플래그	"triggered_use_cases": { "type": "array", "items": { "type": "string" } },
"has_knowledge_response_attempt"	지식 답변이 이해되었는지, 기술 오류가 발생했는지, 가벼운 대화였는지 등과 관계없이 대화가 지식 대화였는지(지식 답변이 하나 이상 있음) 식별하는 플래그	"has_knowledge_response_attempt": { "type": "boolean" },
"knowledge_notUnderstood_count"	지식 대화에서 이해되지 않은 메시지의 수. 에이전틱 지식 응답의 경우에는 AI 상담사가 응답을 생성하기 위해 적절한 지식 소스와 질문을 일치시키지 않은 후속 질문이 포함될 수 있습니다.	"knowledge_notUnderstood_count": { "type": "string" },
"knowledge_responseGenerated_count"	지식 대화에서 응답이 생성된 메시지의 수	"knowledge_responseGenerated_count": { "type": "string" },
"knowledge_errorOccurred_count"	지식 대화에서 오류가 발생한 메시지의 수	"knowledge_errorOccurred_count": { "type": "string" },
"knowledge_escalationRequired_count"	지식 대화에서 에스컬레이션이 필요했던 메시지의 수. 이 상태는 생성형 답장이 처리한 지식 응답에만 적용됩니다.	"knowledge_escalationRequired_count": { "type": "string" },
"knowledge_fallback_count"	지식 대화에서 대체 메시지의 수	"knowledge_fallback_count": { "type": "string" },
"knowledge_sources"	대화에서 사용된 지식창고 유형, 문서 제목 및 URL 목록	"knowledge_sources": { "type": "array", "items": { "type": "string" } },
"bot_messages_count"	AI 상담사 메시지의 수	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	고객 메시지의 수	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	일반적으로 이해되지 않은 메시지의 수	"not_understood_messages_count": { "type": "string" },

응답 예시

API 호출의 응답은 GET 요청으로 액세스할 수 있는 Google 스토리지 버킷의 파일에 대한 URL 링크입니다.

{"date":"2024-05-03","urls":["https://storage.googleapis.com/production-eu-ultimateai-backend-data-export/files/your_bot_id/2024-05-0/conversation_your_bot_id_20240503_000000000000.json…"]}

파일에는 다음 형식에 따라 각 대화가 json 개체로 포함되어 있습니다.

{
  "bot_id": "98174e8d635471c383b9ec7b",
  "bot_name": "INDUSTRY DEMO (Travel) - SunCo",
  "conversation_id": "67bc4129-6609-4v67-869d-db1d0186d1d8",
  "platform_conversation_id": "57459bd72555b8452378f693",
  "conversation_start_time": "2024-05-03T08:10:01.211+00:00",
  "conversation_end_time": "2024-05-03T08:10:25.744+00:00",
  "language": "eng",
  "channel": "chat",
  "labels": [
    "web",
    "API:getBookingDetails-Success"
  ],
  "conversations_data": {
    "bsatScore" : 5,
    "convoId": "552cd72556e8452378d344",
    "email": null,
    "location": null,
    "confidence_score": 95,
    "lastDetectedLanguage": "eng",
    "lastDetectedSentiment": "neutral",
    "usedLanguage": "eng",
    "channel": "web",
    "bookingNo": null,
    "booking": 
    [{
      "country": "Spain",
      "url": "https://cdn.pixabay.com/photo/2015/05/05/01/10/house-753270__340.jpg",
      "location": "41.3485806,1.9787689",
      "city": "Barcelona",
      "numOfGuests": 4,
      "days": 4,
      "arrivalDate": "12-12-2022"
    }],
    "city": "Barcelona",
    "manageBooking": "possible"
  },
  "test_mode": false,
  "conversation_status": "botHandled",
  "last_resolution": "resolved"
  "triggered_replies": [
  {
    "reply_timestamp": "2024-05-03T08:10:02.991+00:00",
    "reply_id": "53628e8e55b4f2459bcb2e72",
    "reply_language": "eng",
    "reply_name": "Greeting",
    "reply_type": "normal",
    "intent_id": "64628b8e55e4f2459bcb2e68"
  },
  {
    "reply_timestamp": "2024-05-03T08:10:03.355+00:00",
    "reply_id": "64628e8e55e4f2459bcb2f4b",
    "reply_language": "eng",
    "reply_name": "Welcome reply",
    "reply_type": "welcome"
  },
  {
    "reply_timestamp": "2024-05-03T08:10:12.951+00:00",
    "reply_id": "2475e571f88f9c35af3ff45e",
    "reply_language": "eng",
    "reply_name": "Office or store location and opening hours",
    "reply_type": "normal",
    "intent_id": "6385e571f88f9c35af3ff46e"
  }
  ],
  "triggered_intent_replies": [
  {
    "intent_timestamp": "2024-05-03T08:10:02.991+00:00",
    "intent_id": "53628e8e55b4f2459bcb2e72",
    "intent_name": "Greeting",
    "not_meaningful": true
  },
  {
    "intent_timestamp": "2024-05-03T08:10:12.951+00:00",
    "intent_id": "6375b571f88f9c35af3ff44e",
    "intent_name": "Find location of rental",
    "not_meaningful": false
  }
  ],
  "is_llm_conversation": false,
  "bot_messages_count": "7",
  "customer_messages_count": "4",
  "not_understood_messages_count": "0"
}

인기 메트릭

축하합니다! AI 상담사의 대화 데이터를 내보냈습니다. 다음은 내보낸 파일의 데이터 탐색 여정을 시작하기 위한 일부 제안입니다.

AI 상담사 메트릭

SELECT
--Total conversations
count(distinct conversation_id) total_conversations,

--AI agent handled rate
count(distinct case when conversation_status = 'botHandled' then conversation_id end) bot_handled_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate,

--Deflection rate
count(distinct case when conversation_status not in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) deflection_rate,

--Escalation rate
count(distinct case when conversation_status in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) escalation_rate,

--Failed escalation rate
count(distinct case when conversation_status = 'failedEscalation' then conversation_id end)/count(distinct conversation_id) failed_escalation_rate,

--Message understood rate
(sum(customer_messages_count)-sum(not_understood_messages_count
))/sum(customer_messages_count) messages_understood_rate

FROM TABLE

대화의 첫 번째/마지막 의도

select 
distinct conversation_id,
triggered_use_cases[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE

자주 묻는 질문(FAQ)

• 내보낸 파일은 변경할 수 없나요? 아니면 시간이 지남에 따라 변경되므로 다시 동기화해야 하나요?
  내보낸 파일은 변경할 수 없으므로 다시 가져올 필요가 없고, 따라서 BI 파이프라인에 오류가 발생할 가능성이 적습니다.
• 내보낸 대화와 AI 상담사 요약 애널리틱스 간에 특정 날짜의 대화 수가 다릅니다. 그 이유가 무엇일까요?
  특정 날짜의 내보낸 데이터에는 해당 날짜에 종료된 대화에 대한 데이터만 있습니다. 이는 모든 상태의 대화가 포함되는 AI 상담사 요약 애널리틱스와는 다른 접근 방식입니다. 내보내기 파일의 불변성 및 중복 데이터 방지를 포함한 여러 가지 이유로 인한 것일 수 있습니다.
• AI 상담사 요약과 내보낸 파일에서 보고된 수치 간의 동등성을 어떻게 달성할 수 있나요?
  x라는 특정 날에 발생한 모든 대화를 전체적으로 보려면 x일과 x + 1일에 대해 생성된 파일을 수집하면 됩니다. 이러한 두 날짜의 파일을 수집하면 다음 날로 넘어간 경우에도 날짜 x에 대한 모든 대화를 계산할 수 있습니다.
• 내보낸 대화와 대화 로그 간에 특정 날짜의 대화 수가 다릅니다. 그 이유가 무엇일까요?
  특정 날짜의 내보낸 데이터에는 해당 날짜에 종료된 대화에 대한 데이터만 포함되어 있다는 점을 기억하세요. 이는 실시간 디버깅을 사용하기 위해 모든 상태의 대화를 포함하는 대화 로그와는 다른 접근 방식입니다.
• 전날에 발생한 답장이더라도 대화에서 트리거된 모든 답장에 대한 정보가 포함되어 있나요?
  예. 대화가 파일에 포함되면 전날에 발생했더라도 모든 데이터가 포함됩니다.
• 가상 상담사가 추천 엔진의 일부로 대화를 나누고 있는데, 그러한 대화가 내보내기에 표시되나요?
  예. AI 상담사 요약 대시보드에서는 이러한 대화가 제외되지만, 내보낸 데이터에는 계속 표시됩니다. 이러한 대화를 제외하고 AI 상담사 요약 대시보드와의 동등성을 달성하려면 "bot_messages_count > 0"으로 필터링하세요.