7.9 KiB
7.9 KiB
历史记录 (History Records) API
历史记录 API 用于管理通话记录和对话历史。
基础信息
| 项目 | 值 |
|---|---|
| Base URL | /api/v1/history |
| 认证方式 | Bearer Token (预留) |
数据模型
CallRecord
interface CallRecord {
id: string; // 通话记录ID
user_id: number; // 所属用户ID
assistant_id?: string; // 关联助手ID
source: string; // 来源: "debug" | "external"
status: string; // 状态: "connected" | "missed" | "failed"
started_at: string; // 开始时间 ISO8601
ended_at?: string; // 结束时间 ISO8601
duration_seconds?: int; // 通话时长(秒)
summary?: string; // 通话摘要
cost?: number; // 费用
metadata?: object; // 元数据
created_at: string; // 创建时间
}
TranscriptSegment
interface TranscriptSegment {
turn_index: int; // 对话轮次
speaker: string; // 说话者: "human" | "ai"
content: string; // 转写内容
confidence?: float; // 置信度 0-1
start_ms: int; // 开始时间(毫秒)
end_ms: int; // 结束时间(毫秒)
duration_ms?: int; // 持续时间(毫秒)
audio_url?: string; // 音频URL
emotion?: string; // 情绪标签
}
InteractionDetail
interface InteractionDetail {
role: "user" | "assistant"; // 角色
content: string; // 文本内容或转写文本
audio_url?: string; // 音频URL
image_urls?: string[]; // 图片URL列表(视频场景)
timestamp: string; // 时间戳
}
API 端点
1. 获取通话记录列表
GET /api/v1/history
Query Parameters:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| assistant_id | string | 否 | 过滤助手ID |
| status | string | 否 | 过滤状态: "connected" | "missed" | "failed" |
| source | string | 否 | 过滤来源: "debug" | "external" |
| start_date | string | 否 | 开始日期 ISO8601 |
| end_date | string | 否 | 结束日期 ISO8601 |
| page | int | 否 | 页码，默认 1 |
| limit | int | 否 | 每页数量，默认 20 |
Response:
{
"total": 150,
"page": 1,
"limit": 20,
"list": [
{
"id": "call_001",
"user_id": 1,
"assistant_id": "abc12345",
"source": "debug",
"status": "connected",
"started_at": "2024-01-15T14:30:00Z",
"ended_at": "2024-01-15T14:33:00Z",
"duration_seconds": 180,
"summary": "用户咨询产品A的售后服务",
"cost": 0.05,
"created_at": "2024-01-15T14:30:00Z"
},
{
"id": "call_002",
"user_id": 1,
"assistant_id": "abc12345",
"source": "external",
"status": "missed",
"started_at": "2024-01-15T14:00:00Z",
"duration_seconds": 0,
"created_at": "2024-01-15T14:00:00Z"
}
]
}
2. 获取通话详情
GET /api/v1/history/{call_id}
Response:
{
"id": "call_001",
"user_id": 1,
"assistant_id": "abc12345",
"source": "debug",
"status": "connected",
"started_at": "2024-01-15T14:30:00Z",
"ended_at": "2024-01-15T14:33:00Z",
"duration_seconds": 180,
"summary": "用户咨询产品A的售后服务",
"cost": 0.05,
"metadata": {
"browser": "Chrome",
"os": "Windows"
},
"transcripts": [
{
"turn_index": 0,
"speaker": "human",
"content": "您好，我想咨询一下产品A的售后服务",
"confidence": 0.98,
"start_ms": 0,
"end_ms": 3500,
"duration_ms": 3500,
"audio_url": "https://storage.example.com/audio/call_001/turn_0.mp3"
},
{
"turn_index": 1,
"speaker": "ai",
"content": "您好！产品A享有7天无理由退货和一年质保服务。请问您遇到了什么问题？",
"confidence": 0.95,
"start_ms": 4000,
"end_ms": 12000,
"duration_ms": 8000,
"audio_url": "https://storage.example.com/audio/call_001/turn_1.mp3"
},
{
"turn_index": 2,
"speaker": "human",
"content": "我发现产品A有一个功能坏了",
"confidence": 0.92,
"start_ms": 13000,
"end_ms": 18000,
"duration_ms": 5000,
"audio_url": "https://storage.example.com/audio/call_001/turn_2.mp3"
}
]
}
3. 创建通话记录
POST /api/v1/history
Request Body:
{
"user_id": 1,
"assistant_id": "abc12345",
"source": "debug"
}
Response:
{
"id": "call_new001",
"user_id": 1,
"assistant_id": "abc12345",
"source": "debug",
"status": "connected",
"started_at": "2024-01-15T15:00:00Z",
"created_at": "2024-01-15T15:00:00Z"
}
4. 更新通话记录
PUT /api/v1/history/{call_id}
Request Body:
{
"status": "connected",
"summary": "用户咨询产品A的售后服务，已引导用户提交工单",
"duration_seconds": 180,
"ended_at": "2024-01-15T14:33:00Z"
}
5. 删除通话记录
DELETE /api/v1/history/{call_id}
6. 添加转写片段
POST /api/v1/history/{call_id}/transcripts
Request Body:
{
"turn_index": 3,
"speaker": "ai",
"content": "好的，我已经为您创建了工单，编号 #12345，请保持电话畅通，我们的客服人员会在24小时内联系您。",
"confidence": 0.96,
"start_ms": 20000,
"end_ms": 28000,
"duration_ms": 8000,
"emotion": "neutral"
}
Response:
{
"id": 100,
"turn_index": 3,
"speaker": "ai",
"content": "好的，我已经为您创建了工单...",
"confidence": 0.96,
"start_ms": 20000,
"end_ms": 28000,
"duration_ms": 8000,
"audio_url": "https://storage.example.com/audio/call_001/turn_3.mp3",
"emotion": "neutral"
}
7. 获取音频
GET /api/v1/history/{call_id}/audio/{turn_index}
Response: 重定向到音频文件 URL
Schema 定义
# ============ Call Record ============
class CallRecordSource(str, Enum):
DEBUG = "debug"
EXTERNAL = "external"
class CallRecordStatus(str, Enum):
CONNECTED = "connected"
MISSED = "missed"
FAILED = "failed"
class CallRecordBase(BaseModel):
assistant_id: Optional[str] = None
source: str = "debug"
class CallRecordCreate(CallRecordBase):
pass
class CallRecordUpdate(BaseModel):
status: Optional[str] = None
summary: Optional[str] = None
duration_seconds: Optional[int] = None
ended_at: Optional[str] = None
cost: Optional[float] = None
metadata: Optional[dict] = None
class TranscriptSegment(BaseModel):
turn_index: int
speaker: str # "human" | "ai"
content: str
confidence: Optional[float] = None
start_ms: int
end_ms: int
duration_ms: Optional[int] = None
emotion: Optional[str] = None
class CallRecordOut(BaseModel):
id: str
user_id: int
assistant_id: Optional[str] = None
source: str
status: str
started_at: str
ended_at: Optional[str] = None
duration_seconds: Optional[int] = None
summary: Optional[str] = None
cost: float = 0.0
metadata: dict = {}
created_at: datetime
transcripts: List[TranscriptSegment] = []
class Config:
from_attributes = True
class TranscriptCreate(BaseModel):
turn_index: int
speaker: str
content: str
confidence: Optional[float] = None
start_ms: int
end_ms: int
duration_ms: Optional[int] = None
emotion: Optional[str] = None
class TranscriptOut(TranscriptCreate):
id: int
audio_url: Optional[str] = None
class Config:
from_attributes = True
Web 端对应接口映射
| Web Type | API Endpoint |
|---|---|
| CallLog (list) | GET /api/v1/history |
| CallLog (detail) | GET /api/v1/history/{id} |
| InteractionDetail | GET /api/v1/history/{id} (transcripts 字段) |