对话 API

概述

对话 API 是智企云工最核心的 API 接口。通过调用此接口，你可以在自己的应用（网站、小程序、App 等）中集成 AI 客服对话能力，无需使用默认的网页浮窗。

发起对话

请求

POST https://api.zhiqiyungong.com/api/kf/ask
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Tenant-Id: tnt_7x2m9p1q

{
  "project_id": "prj_m4k8n2x7",
  "question": "你们的营业时间是什么？",
  "user_id": "user_12345",           // 可选，用户唯一标识
  "session_id": "sess_abc123",      // 可选，会话 ID，用于多轮对话
  "channel": "api"                  // 可选，渠道标识
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "answer": "我们的营业时间为周一至周五 9:00-18:00，周末及法定节假日休息。如有紧急情况，请拨打客服热线 400-XXX-XXXX。",
    "confidence": 0.92,             // 匹配置信度 (0-1)
    "source": "knowledge",          // 回答来源：knowledge / ai_generate / fallback
    "session_id": "sess_abc123",    // 会话 ID，下次对话需携带
    "matched_knowledge_id": "kb_001" // 匹配的知识 ID（如果来自知识库）
  }
}

多轮对话

智企云工支持多轮对话。首次调用时可以不传 session_id，系统会自动创建会话并返回 session_id。后续对话携带此 session_id，AI 会结合上下文理解用户意图。

// 第一轮对话
POST /api/kf/ask
{
  "project_id": "prj_m4k8n2x7",
  "question": "我想了解你们的产品"
}
// 响应返回 session_id: "sess_abc123"

// 第二轮对话（携带 session_id）
POST /api/kf/ask
{
  "project_id": "prj_m4k8n2x7",
  "question": "价格是多少？",        // AI 会理解"价格"指的是产品价格
  "session_id": "sess_abc123"       // 保持上下文
}

流式响应（SSE）

对于需要实时展示回答的场景（类似 ChatGPT 的打字效果），可以使用 Server-Sent Events (SSE) 流式响应：

POST https://api.zhiqiyungong.com/api/kf/ask/stream
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: text/event-stream

{
  "project_id": "prj_m4k8n2x7",
  "question": "介绍一下你们的产品",
  "session_id": "sess_abc123"
}

// 响应 (SSE 格式)
data: {"type": "chunk", "content": "智企云工是一套"}
data: {"type": "chunk", "content": "面向企业的 AI SaaS 平台"}
data: {"type": "chunk", "content": "，包含云工客服和营销宝两大产品。"}
data: {"type": "done", "session_id": "sess_abc123"}

前端 JavaScript 示例：

const response = await fetch('https://api.zhiqiyungong.com/api/kf/ask/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token,
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({ project_id, question })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let answer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  const lines = text.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'chunk') {
        answer += data.content;
        // 实时更新 UI
        updateAnswer(answer);
      }
    }
  }
}

获取对话历史

GET /api/kf/conversations?project_id=prj_m4k8n2x7&session_id=sess_abc123&page=1&page_size=20
Authorization: Bearer YOUR_ACCESS_TOKEN

// 响应
{
  "code": 0,
  "data": {
    "messages": [
      {"role": "user", "content": "营业时间是什么？", "created_at": "2026-05-18T10:00:00+08:00"},
      {"role": "assistant", "content": "我们的营业时间为周一至周五 9:00-18:00...", "created_at": "2026-05-18T10:00:01+08:00"}
    ],
    "total": 2,
    "page": 1
  }
}

注意事项

• 免费版每月 100 次 AI 对话配额，超出后返回 403 错误
• 单次对话请求超时时间为 30 秒
• 会话有效期为 24 小时，过期后自动创建新会话
• 建议在前端实现错误重试机制，网络波动时自动重试 1-2 次