查询会话详情¶
读取一个可见会话的展示信息和当前任务关联。可用查询参数限制读取的智能体范围。
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/{conversation_id}
调用前准备¶
请求参数¶
curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
--data-urlencode "agent_id=$AGENT_ID"
字段 |
类型 |
必填 |
说明 |
|---|---|---|---|
|
string |
是 |
当前工作区 ID，必须与 X-Workspace-ID 一致。 |
|
string |
是 |
要查看的会话 ID。 |
字段 |
类型 |
必填 |
说明 |
|---|---|---|---|
|
string |
否 |
仅返回属于该智能体的会话。未提供时不按智能体 ID 过滤。 |
|
string |
否 |
智能体所属工作区 ID。未提供时，且指定了 agent_id，使用当前工作区；只能指定当前工作区或系统工作区。 |
成功响应¶
{
"code": 0,
"data": {
"id": "conv_01",
"workspace_id": "ws_01",
"agent_workspace_id": "ws_01",
"agent_id": "agent_01",
"agent_summary": {
"id": "agent_01",
"display_name": "销售分析助手",
"available": true
},
"title": "销售分析",
"status": "active",
"purpose": "chat",
"visibility": "visible",
"pinned": true,
"head_message_id": "msg_01",
"active_task_id": "task_01",
"last_message_at": "2026-01-02T15:04:05Z",
"created_at": "2026-01-02T15:04:05Z",
"updated_at": "2026-01-02T15:04:05Z"
}
}
成功时返回 200。data 是当前会话的完整展示信息。
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
成功时为 0。 |
字段 |
类型 |
说明 |
|---|---|---|
|
string |
会话 ID。 |
|
string |
会话所属工作区 ID。 |
|
string |
智能体所属工作区 ID。 |
|
string |
智能体 ID。 |
|
object |
智能体展示摘要；可包含 id、display_name、avatar_ref、status、available 和 unavailable_reason。 |
|
string |
会话标题；未设置时不返回。 |
|
string |
会话状态。 |
|
string |
会话用途。 |
|
string |
会话可见性。 |
|
boolean |
是否置顶。 |
|
string |
最近消息 ID；尚无消息时不返回。 |
|
string |
当前活动任务 ID；没有活动任务时不返回。 |
|
string |
最近消息时间；尚无消息时不返回。 |
|
string |
创建和最近更新时间，采用 RFC 3339 格式。 |
|
string |
创建和最近更新时间，采用 RFC 3339 格式。 |
错误响应¶
{
"code": 3,
"message": "会话不存在"
}
字段 |
类型 |
说明 |
|---|---|---|
|
|
路径参数或智能体查询参数为空、包含不允许的路径分隔符，或智能体工作区不在允许范围。建议：检查会话 ID、 |
|
|
会话不存在、不可见，或不属于指定的智能体范围。建议：确认会话 ID 和筛选条件；必要时移除智能体筛选后重试。 |
|
|
服务端无法读取会话或生成智能体展示信息。建议：记录请求时间和错误信息后重试。 |
|
|
会话服务暂不可用。建议：稍后重试。 |