會話
請求補拉對話歷史
僅為 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 路由嘅 ID。
請求內容
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 與工作區是否有效。