What's my plan?
Add-on AI agents - Advanced

我们的数据导出 API 是释放人工智能专员全部潜力的钥匙，使您能够导出对话数据，并将其在不同的平台和应用程序之间进行整合。

无论您是开发者、业务分析师还是 IT 专业人士，我们的 API 都能提供一个精简而安全的解决方案来提取有价值的见解和对话元数据，使您能够推动创新、做出明智的决策，并将您的组织发展推向新的高度。

本文章包含以下主题：

  • 获取组织 ID
  • 生成 API 密钥
  • 关于 API
  • 文件架构
  • 响应示例
  • 常用指标
  • 常见问题解答

获取组织 ID

此步骤只能由具有管理员用户角色的用户完成

  1. 在左侧栏中，单击 组织管理。
    注意：如果您在 2024 年 10 月 7 日之前购买了人工智能专员（高级），请单击 用户管理> 而改为 组织管理 。
  2. 单击您的组织以打开其个人资料。
  3. 在您的浏览器中找到您的组织 ID： 
    https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s

生成 API 密钥

生成密钥只能由具有管理员角色的用户完成

  1. 在左侧栏中，单击 组织管理。
    注意：如果您在 2024 年 10 月 7 日之前购买了人工智能专员（高级），请单击 用户管理> 而改为 组织管理 。
  2. 单击您的组织以打开其个人资料。
  3. 选择 API 密钥 标签。
  4. 单击 生成。
  5. 单击保存。
  6. 复制密钥并妥善保存。

Screenshot 2024-02-07 at 10.29.51.png

退出组织管理页面后，您将无法访问密钥。如果您丢失了之前生成的密钥，只需单击 “重新生成” 按钮即可撤销。旧密钥的有效性将被撤销，您可以使用新生成的密钥。

关于 API

数据导出 API 每天更新一次，更新时间为 UTC（世界协调时间）午夜。此更新过程可能会运行一段时间，因此在 UTC 时间一大早运行导入有助于确保数据已存在。

对于欧盟： POST- https://api.ultimate.ai/data-export/v2/get-signed-urls

对于美国： POST- https://api.us.ultimate.ai/data-export/v2/get-signed-urls

页首

name

必填

type

botId

true

string

organizationId

true

string

authorization

true

string

正文

name

必填

type

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" 客户关系管理特定 ID 
 "platform_conversation_id": {
"type": "string"
},
"conversation_start_time" 对话开始的日期和时间（UTC 时区） 
"conversation_start_time": {
"type": "string"
},
"conversation_end_time" 对话结束的日期和时间（UTC 时区） 
"conversation_end_time": {
"type": "string"
},
"language" 对话的语言 
"language": {
"type": "string"
},
"channel" 对话的渠道。消息传送或电邮 
"channel": {
"type": "string"
},
"labels" 与对话关联的所有标签的列表 
"labels": {
"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_handle 
"conversation_status": {
"type": "string"
},
"last_ resolution" 这是对话的最终解决方案。它可以是已通知、已解决、已升级或未定义。 
"last_resolution": {
"type": "string"
},
"triggered_replies"   
"triggered_replies": {
"type": "array",
"items": {
"type": "string"
   }
},
"triggered_intent_replies"

基于意向的回复

 
"triggered_intent_replies": {
"type": "array",
"items": {
"type": "string"
   }
},
"is_llm_conversation" 一个标记，用于识别对话是否为 LLM 对话（至少有一个 LLM 答案） 
"is_llm_conversation": {
"type": "boolean"
},
"llm_notUnderstood_count" LLM 对话中未理解的消息数 
"llm_notUnderstood_count": {
"type": "string"
},
"llm_responseGenerating_count" LLM 对话中响应生成消息的数量 
"llm_responseGenerated_count": {
"type": "string"
},
"llm_errorOccured_count" LLM 对话中发生错误的消息数 
"llm_errorOccurred_count": {
"type": "string"
},
"llm_escalationrequired_count" LLM 对话中escalationrequired 消息的数量 
"llm_escalationRequired_count": {
"type": "string"
},
"llm_allback_count" LLM 对话中的回退消息数 
"llm_fallback_count": {
"type": "string"
},
"bot_messages_count" 人工智能专员消息数 
"bot_messages_count": {
"type": "string"
},
"customer_messages_count" 客户消息数 
 "customer_messages_count": {
"type": "string"
},
"not_understood_messages_count" 一般未理解的消息数 
"not_understood_messages_count": {
"type": "string"
},

响应示例

API 调用的响应是一个 URL 链接，指向 Google 存储桶中的一个文件，您可以使用 GET 请求访问该文件：

{"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"
}

常用指标

恭喜！您已成功导出人工智能专员的对话数据。以下是我们的一些建议，便于您开始探索导出的文件。

人工智能专员 指标

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

--Bot 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,

--Informed rate
count(distinct case when last_resolution = 'informed' then conversation_id end)/count(distinct conversation_id) informed_rate,

--Custom resolution rate
count(distinct case when last_resolution in ('informed', 'resolved') then conversation_id end)/count(distinct conversation_id) automation_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_intent_replies[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE

按首次有意义（或已过滤）意向划分的指标

with meaningful_intents as (
select conversation_id, first_meaningful_intent, conversation_status from 
(
select distinct conversation_id,
intent.intent_name first_meaningful_intent,
conversation_status,
--order by ascending intent_timestamp for last intent
ROW_NUMBER() OVER (PARTITION BY conversation_id order by intent.intent_timestamp asc) rn,
FROM TABLE
LEFT JOIN UNNEST(triggered_intent_replies) intent
--select only intents that are labeled as meaningful
where intent.not_meaningful is false 
--filter for specific intents
and intent.intent_name not in ('Greeting', 'Talk to a human/agent')
)
where rn=1
)

--calculate metrics for each intent
select first_meaningful_intent,
count(distinct conversation_id) total_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate
from meaningful_intents
group by first_meaningful_intent
order by total_conversations desc

常见问题解答

  • 导出的文件是一成不变的，还是会随着时间的推移而改变，需要您重新同步？
    导出的文件不可变，因此无需重新导入，从而降低了 BI 管道出错的可能性。
  • 我发现导出的对话和 人工智能专员 概要分析之间特定日期的对话计数存在差异。可能是什么原因？
    特定日期的导出数据仅包含在该日期结束的对话的数据。这与 人工智能专员概要 分析不同，后者包含任何状态的任何对话。这样做的原因有多种，其中包括：导出文件的不变性和防止重复的数据。
  • 那么如何实现 人工智能专员 概要中报告的数字和导出的文件之间的平衡？
    要获取在某个 x 发生的所有对话的完整概览，您可以提取为第 x 天和 x + 1 天生成的文件。通过从这两个日期提取文件，您可以确保计算了 x 日期的所有对话，即使其溢出到了第二天。
  • 我发现导出的对话和对话日志之间特定日期的对话计数存在差异。可能是什么原因？
    请记住，特定日期的导出数据仅包含在该日期结束的对话的数据。这与在对话日志中采用的方法不同，后者包含任何状态的任何对话，以便进行实时调试。
  • 对话是否包含关于在对话中触发的所有回复的信息，即使这些回复发生在前一天？
    是。如果文件中包含对话，则它将包含其所有数据，即使它发生在前一天。
  • 我的虚拟专员有建议引擎中的对话，它们会显示在导出中吗？
    可以。尽管在 人工智能专员 概要面板中这些已排除，但仍会显示在导出的数据中。要排除这些消息，并与 人工智能专员 概要面板对标，请按“bot_messages_count”进行筛选 > 0"。

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。

由 Zendesk 提供技术支持