API 参考

ServiceGo API 基于 RESTful 设计，所有接口均以 /api/v1 为前缀。 受保护的接口需要在请求头中携带 JWT Token。

认证

通过登录接口获取 Token，在后续请求中携带：

Authorization: Bearer <your-jwt-token>

公开接口

以下接口无需认证，用于客户端（Widget）调用：

创建/恢复会话

POST /api/v1/chat/session
Content-Type: application/json

{
  "tenantId": "uuid",
  "channel": "web",
  "anonymousId": "random-uuid"
}

// Response: { "sessionId": "uuid", "userId": "uuid" }

发送消息（同步）

POST /api/v1/chat/message
Content-Type: application/json

{
  "sessionId": "uuid",
  "message": "你好，请问..."
}

// Response: { "reply": "AI 回复内容" }

发送消息（SSE 流式）

GET /api/v1/chat/stream?sessionId=uuid&message=你好

// Response: text/event-stream
// data: {"type":"delta","content":"你"}\n\n
// data: {"type":"delta","content":"好"}\n\n
// data: {"type":"done"}\n\n

受保护接口

以下接口需要 JWT 认证，用于管理后台调用：

会话管理

方法	路径	说明
GET	/api/v1/sessions	列出会话（支持状态/语言筛选）
GET	/api/v1/sessions/:id	会话详情
GET	/api/v1/sessions/:id/history	消息历史
PATCH	/api/v1/sessions/:id	更新会话状态

人工转接

方法	路径	说明
GET	/api/v1/handoffs	待接手列表
PATCH	/api/v1/handoffs/:id/accept	接手会话
PATCH	/api/v1/handoffs/:id/transfer	转交其他坐席
PATCH	/api/v1/handoffs/:id/close	关闭转接

知识库

方法	路径	说明
GET	/api/v1/knowledge-bases	列出知识库
POST	/api/v1/knowledge-bases	创建知识库
POST	/api/v1/knowledge-bases/:id/documents	上传文档
DELETE	/api/v1/knowledge-bases/:id	删除知识库

Agent 配置

方法	路径	说明
GET	/api/v1/agent-configs	列出 Agent
POST	/api/v1/agent-configs	创建 Agent
PATCH	/api/v1/agent-configs/:id	更新配置
DELETE	/api/v1/agent-configs/:id	删除 Agent

WebSocket

坐席端通过 WebSocket 接收实时消息推送：

ws://your-api-domain.com/ws?sessionId=uuid

// 收到消息类型:
// {"type":"delta","content":"..."} — AI 流式输出
// {"type":"done"} — 回复完成
// {"type":"handoff","handoffId":"uuid"} — 转人工通知

错误处理

所有错误返回统一格式：

{
  "error": {
    "message": "错误描述",
    "status": 400
  }
}

状态码	说明
400	请求参数错误
401	未认证或 Token 过期
404	资源不存在
429	请求频率超限
500	服务器内部错误