接口介绍
批量删除原始对话消息。通过以下两种方式之一指定删除范围，二选其一：
按 message id 批量删：通过
message_ids 传入消息主键数组（非空），按主键精确删除一组消息。按 session 批量删：通过
session_id 传入会话 ID，一次性删除该会话下的全部消息。项 | 值 |
HTTP 方法与路径 | POST /v2/conversation/delete |
HTTP 文档 | |
函数签名 | delete_conversation(*, message_ids=None, session_id=None) |
说明：
message_ids 与 session_id 必须二选其一传入，全部缺省或同时传入均返回业务错误码 400，避免空筛选导致整租户全量数据被删、或两者并用导致删除范围出现二义性。建议先用 query_conversation 预览将被命中的范围，再执行删除。使用示例
# 按 message_ids 精确删result = client.delete_conversation(message_ids=["msg-aaaa", "msg-bbbb"])print(f"实际删除 {result['deleted_count']} 条")# 按 session_id 整会话删result = client.delete_conversation(session_id="sess-trip-202604")
说明：
请求参数
参数名 | 类型 | 必填 | 描述说明 |
message_ids | List[str] | 二选一 | 消息 ID 列表。 互斥规则：与 session_id 必须二选一传入，不可同时为空，也不建议同时传入。 约束条件：传入的数组必须包含至少 1 个有效的消息 ID（不可传空数组 []）。 |
session_id | str | 二选一 | 会话 ID。 互斥规则：与 message_ids 必须二选一传入。 应用场景：当需要直接指定整个会话、而不是筛选具体某几条消息时使用。 |
返回信息
返回字典包含本次实际删除的条数与请求追踪 ID：
{"deleted_count": 2,"trace_id": "tr-xxxxxxxx-xxxxxxxx"}
字段 | 类型 | 说明 |
deleted_count | int | 实际成功删除的消息总条数。 说明： 当使用 message_ids 列表进行批量删除时，如果传入了不存在、已被删除、或不属于当前用户/会话的无效 ID，系统将执行静默跳过（自动忽略）且不会报错。这些无效 ID 将不会被计入 deleted_count 中。 |
trace_id | str | 请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，方便追踪大批量高危写/删操作。 |
错误处理
错误码 | 触发场景 | 处理建议 |
400 | 两个参数全部缺省、同时传入、或 message_ids 为空数组。 | 检查互斥语义后重试。 |
500 | 服务端错误。 | 记录 trace_id 后重试或上报。 |
