我们的数据导出 API 是释放人工智能专员全部潜力的钥匙，使您能够导出对话数据，并将其整合到不同的平台和应用程序中。
无论您是开发者、业务分析师还是 IT 专业人士，我们的 API 都能提供一个简化而安全的解决方案，用于提取有价值的见解和对话元数据，使您能够推动创新、做出明智的决策，并将您的组织发展到新的高度。
本文章包含以下主题：
获取组织 ID
此步骤只能由具有管理员用户角色的用户完成
- 在左侧栏中，单击 组织管理。
注意：如果您在 2024 年 10 月 7 日之前购买了人工智能专员（高级），请单击 用户管理> 而是 组织管理 。
- 单击您的组织以打开其个人资料。
- 在浏览器的 URL 中找到您的组织 ID：
https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s
生成 API 密钥
生成密钥只能由具有管理员角色的用户完成
- 在左侧栏中，单击 组织管理。
注意：如果您在 2024 年 10 月 7 日之前购买了人工智能专员（高级），请单击 用户管理> 而是 组织管理 。
- 单击您的组织以打开其个人资料。
- 选择 API 密钥 标签。
- 单击 生成。
- 单击保存。
- 复制密钥并妥善保存。
退出组织管理页面后，您将无法访问密钥。如果您丢失了之前生成的密钥，只需单击 “重新生成” 按钮即可撤销。旧密钥的有效性将被撤销，您可以使用新生成的密钥。
关于 API
数据导出 API 每天更新一次，更新时间为午夜 UTC（世界协调时间）。此更新过程可能会运行一段时间，因此在 UTC 时间一大早运行导入有助于确保数据已经存在。
对于欧盟： POST- https://api.ultimate.ai/data-export/v3/get-signed-urls
对于美国： POST- https://api.us.ultimate.ai/data-export/v3/get-signed-urls
页首
|
name |
必填 |
type |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
正文
|
name |
必填 |
type |
|---|---|---|
|
|
|
|
响应
|
HTTP 代码 |
响应 |
|---|---|
|
200 |
|
|
401 |
未授权 |
|
500 |
内部服务器错误 |
注意：
- 文件的 URL 会在请求日期一天后过期。要获取有效链接，可再次执行 API 调用。
- 您可请求追溯至 2024 年 1 月 1 日的数据。如果您需要更早的数据， 请联系 Zendesk 客户支持 寻求帮助。
文件架构
API 的输出是一个 JSON 文档，其中包含特定日期的所有对话，其结构如下：
- 该文件是一个 JSON 对象列表，其中每个对象是一个对话
- 文件的名称约定为 conversation_bot-id_date_000000000000.json
| 属性 | 描述 | 类型 |
| "bot_id" | 智能机器人的唯一 ID |
"bot_id": {
|
| "bot_name" | 智能机器人的名称 |
"bot_name": {
|
| "conversation_id" | 生成的对话 ID |
"conversation_id": {
|
| "platform_conversation_id" | 客户关系管理特定 ID |
"platform_conversation_id": {
|
| "conversation_start_time" | 对话开始的日期和时间（UTC 时区） |
"conversation_start_time": {
|
| "conversation_end_time" | 对话结束的日期和时间（UTC 时区） |
"conversation_end_time": {
|
| "conversation_type" | 对话中已识别的回复类型。可能的值包括用例、知识、混合和其他。 |
"conversation_type": {
|
| "language" | 对话的语言 |
"language": {
|
| "channel" | 对话的渠道。消息传送或电邮 |
"channel": {
|
| "labels" | 与对话关联的所有标签的列表 |
"labels": {
|
| "segments" | 对话中识别的所有细分的列表。了解更多关于细分的信息。 |
"segments": {
|
| "conversations_data" |
会话参数与对话关联。这是参数键值所在的列表。未定义的键不会在此列表中 注意：
例如： "conversations_data": {
|
"conversations_data": {
|
|
"test_Mode"
|
用于识别对话是否为测试对话的标记 |
"test_mode": {
|
| "conversation_status" | 对话解决方案 例如：bot_handled |
"conversation_status": {
|
| "automated_ resolution" | 将对话评估为自动解决的结果。详细了解如何计算自动解决。 |
"automated_resolutions": {
|
| "automated_ resolution_reasoning" | 用于确定对话被标为自动已解决的原因。 |
"automated_resolution_reasoning": {
|
| "last_ resolution" |
这是对话的最终解决方案。它可以是已通知、已解决、已升级或未定义。 我们将于 2026 年 2 月 28 日移除此功能。了解更多关于 即将进行的功能移除的信息。 |
"last_resolution": {
|
| "triggered_replies" | 与回复相关的详情。包括回复 ID、语言、回复名称、回复类型和意向 ID 等信息。 |
"triggered_replies": {
|
| "triggered_procedures" |
包括诸如procedure_id、intent_id、use_case_name之类的信息。 对于需要接受零培训的人工智能专员或未触发程序，此部分为空。 |
"triggered_procedures": {
|
| "triggered_use_cases" |
一个标记，用于识别用例是配置为对话还是过程。 |
"triggered_use_cases": {
|
| "has_knowledge_response_attempt" | 一个标记，用于识别对话是否是知识对话（至少有一个知识答案），无论知识答案是否可理解、发生技术错误、是简短的交谈等。 |
"has_knowledge_response_attempt": {
|
| "knowledge_notUnderstood_count" | 知识对话中未理解消息的数量。对于专员的知识回复，这可能包括人工智能专员未将问题与适当的知识来源匹配以生成回复的跟进问题。 |
"knowledge_notUnderstood_count": {
|
| "knowledge_responseGenerating_count" | 知识对话中响应生成的消息数。 |
"knowledge_responseGenerated_count": {
|
| "knowledge_errorOccurrent_count" | 知识对话中发生错误消息的数量。 |
"knowledge_errorOccurred_count": {
|
| "knowledge_escalationrequired_count" | 知识对话中 escalationrequired 消息的数量。此状态仅适用于生成式回复处理的知识回复。 |
"knowledge_escalationRequired_count": {
|
| "knowledge_allback_count" | 知识对话中回退消息的数量。 |
"knowledge_fallback_count": {
|
| "knowledge_sources" | 对话中使用的知识库类型、文章标题和 URL 的列表。 |
"knowledge_sources": {
|
| "bot_messages_count" | 人工智能专员消息的数量 |
"bot_messages_count": {
|
| "visitor_messages_count" | 客户消息数 |
"visitor_messages_count": {
|
| "not_understood_messages_count" | 总体未理解消息的数量 |
"not_understood_messages_count": {
|
响应示例
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,
--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
常见问题解答
-
导出的文件是一成不变的，还是会随着时间的推移而改变，需要您重新同步？
导出的文件不可变，因此不必重新导入，从而使您的 BI 管道更不容易出错。 -
我发现导出的对话和 人工智能专员 概要分析之间在特定日期的对话计数存在差异。可能是什么原因？
特定日期的导出数据仅包含结束于该日期的对话的数据。这与 人工智能专员概要 分析不同，后者包含任何状态的任何对话。这样做有多种原因，其中包括：导出文件的不变性和防止重复数据。 -
那么如何实现 人工智能专员 概要中报告的数字和导出的文件相同的数字呢？
要全面了解在某个 x 发生的所有对话，您可以只提取为第 x 天和 x + 1 天生成的文件。通过从这两个日期提取文件，您可以确保计算了日期 x 的所有对话，即使它已溢出到第二天。 -
我发现导出的对话和对话日志之间特定日期的对话计数存在差异。可能是什么原因？
请记住，特定日期的导出数据仅包含在该日期结束的对话的数据。这与对话日志中的方法不同，后者包含任何状态的任何对话，以便进行实时调试。 -
对话是否包含关于对话中触发的所有回复的信息，即使这些回复发生在前一天？
是。如果文件中包含对话，则它将包含其所有数据，即使它发生在前一天。 -
我的虚拟专员有建议引擎中的对话，这些对话会显示在导出中吗？
可以。尽管在 人工智能专员 概要面板中，这些指标被排除在外，但仍会显示在导出的数据中。要排除这些消息，并使用 人工智能专员 概要面板，请按“bot_messages_count”进行筛选 > 0"。
翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性
如对翻译准确性有任何疑问，请以文章的英语版本为准。