会话
请求补拉会话历史
仅为 provider=whatsapp 私聊请求更早的历史，不包含 whatsapp-protocol。account_id 必须是单个非空路径段，不能包含空白或斜杠（包括编码斜杠）；路径非法返回 400 invalid_request。先订阅 conversation.history，可用批次通过该事件异步返回，携带 data.history.source=on_demand。HTTP 202 和 status=accepted 仅表示受理，不表示收到消息或完成。request_id 仅用于 HTTP 排障，不是任务 ID，不能关联回调。批次可能有多个、重复、晚到或没有回调。继续补拉时，选择已收到的最早且 id、sent_at、direction 完整的原生内容消息构造 before；排除 type=call 合成记录，不要向 before 添加 type。没有下一页游标或完成状态；空批次、数量少于 limit 或超时均不表示历史到底。HTTP 超时后仍可能收到回调，不应自动重试。400 可能返回 invalid_request、provider_invalid_request（包括合成通话锚点），群聊或频道返回 unsupported_conversation_type。其他渠道返回 501 unsupported_by_provider。账号路径有效但账号不存在或不属于当前工作空间时返回 404 account_not_found（numeric_code=20020）；未分类的内部错误返回 500 request_conversation_history_failed（numeric_code=37016）。
https://api.unifyport.ai/v1/accounts/{account_id}/conversations/history/request调用前准备
在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。
参数从哪里取得
- account_id
- 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
请求参数
请求头
X-Api-Key工作区 API Key，工作区由该请求头解析得到。
Content-Type发送 JSON 请求体时使用 application/json。
路径参数
account_id用于该 conversations 路由的标识符。
请求体
conversation_id符合 ^[0-9]+@lid$ 的 WhatsApp 标准私聊 LID，必须属于 before 指向的会话。不接受手机号或其他会话类型。
pattern: ^[0-9]+@lid$
beforeobject必填同一会话中一条原生内容消息的位置；所有字段必须来自该消息且不能为 null。type=call 的合成通话记录即使三个字段完整也无效。请求中不要包含 type。
before同一会话中一条原生内容消息的位置；所有字段必须来自该消息且不能为 null。type=call 的合成通话记录即使三个字段完整也无效。请求中不要包含 type。
message_id含非空白字符的原生内容消息 id。合成通话记录 ID 即使去除首尾空白后仍无效。不能用顶层事件 id 或 HTTP request_id 代替。
minLength: 1 · pattern: \S
sent_at该消息的 RFC3339 发送时间，Unix 秒值必须大于 0。不能用事件 occurred_at 或当前时间代替。
format: date-time
direction消息相对于当前账号的方向：inbound 为接收，outbound 为发送。
enum: inbound, outbound
limit请求数量，不保证实际返回数量。仅省略时默认 50；null、0、非整数和超过 50 均返回 invalid_request。有效范围为 1..50。
minimum: 1 · maximum: 50
如何理解结果
按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。
响应 202 Accepted
{
"request_id": "<REQUEST_ID>",
"data": {
"status": "accepted",
"conversation_id": "100000000000002@lid",
"limit": 50
}
}
响应体
statusaccepted confirms request acceptance only, not receipt of history or completion.
enum: accepted
conversation_idStandard conversation ID for this history request.
limitEffective requested count limit for this history request, from 1 to 50.
minimum: 1 · maximum: 50
响应
202202 Accepted
请求成功，响应体示例如上。
400请求错误
请求体、路径或参数不合法。
401未授权
X-Api-Key 请求头缺失或无效。
404未找到
未找到请求的渠道资源。
409冲突
当前操作与已有的渠道账号或资源冲突。
500服务端错误
服务端遇到了未预期的错误。
501渠道未实现
所选渠道尚未实现该操作。
502上游网关错误
渠道适配器或上游渠道未能完成该操作。
失败后怎么处理
检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。 错误码参考
- invalid_request · 10000 · 400
- 检查必填字段、格式和渠道条件，修正请求后再调用。
- invalid_api_key · 11001 · 401
- 检查 X-Api-Key 是否正确、工作区是否有效。