對話交接與接續對話 API

以交接摘要建立接續對話，並辨識原對話與接續對話的關聯。

當 Agent 在原對話產生交接摘要後，整合端可用摘要訊息建立接續對話。新對話沿用原對話的 Agent 與對話設定，後續訊息則送往新對話。以 API Key 串接的成員，一般對話的建立與送訊息方式請參考建立對話與訊息；匿名 Web Chat 訪客請改用匿名 Web Chat 的後續傳訊。

API 回應的欄位名稱為 camelCase。

使用者在畫面上怎麼整理交接、接續到新對話，以及 Web Chat 要先開哪些設定（對話平台的「啟用對話交接」、Agent 的回覆模式需為 Agent），見使用者手冊的對話交接。

建立接續對話

交接只在 Web Chat 對話提供。匿名 Web Chat 訪客的原對話以 POST /api/conversations/ 送出 {"webChat": "<webChatId>"} 建立，不需帶驗證標頭；webChatId 可在後台 Web Chat 設定頁取得（見快速開始），回應的 id 就是原對話 UUID。

先以 GET /api/conversations/{conversation_id}/ 讀取原對話。匿名訪客不需帶驗證標頭；以 API Key 串接的成員，這個讀取請求與下方建立接續對話的 POST 都要帶 Authorization: Api-Key <您的 API Key>。回應的 handoff.enabled 為 false 表示平台未開啟對話交接，不會產生交接摘要。為 true 時，Agent 產生交接摘要後，handoff.latestSummaryMessageId 會提供該摘要的訊息 UUID；欄位為空表示原對話還沒有交接摘要：摘要只會在使用者於原對話要求交接（例如傳送「交接」、「開新對話繼續」或「handoff」，或點選提示條的「整理交接」），或在上下文用量偏高時 Agent 提議交接、使用者同意後產生，且只有 Agent 或 Team 模式的 Agent 會產生；產生後再讀取一次原對話即可取得。接著向 POST /api/conversations/{conversation_id}/handoff-continuations/ 送出：

{"summaryMessageId": "<原對話內的交接摘要訊息 UUID>"}

summaryMessageId 必須指向這筆原對話內的交接摘要。首次建立回應 HTTP 201；接續對話仍存在時，同一則摘要重送會回應既有對話與 HTTP 200。若先前的接續對話已刪除，重送可建立新對話並回應 HTTP 201。兩種回應都包含：

欄位	意義
conversationId	接續對話的 UUID
title	接續對話標題
created	true 表示本次新建；false 表示取回既有對話

若訊息不屬於原對話，或不是交接摘要，請求會被拒絕。整合端應保存回應的 conversationId，再以它進行後續對話。

匿名 Web Chat 的後續傳訊

匿名 Web Chat 訪客沒有 API Key，不能使用 POST /api/messages/。取得接續對話的 conversationId 後，改用 Web Chat 訊息端點，請求不需帶驗證標頭：

POST /api/conversations/{conversationId}/web-chat-messages/

{"content": "接續上一段的問題"}

對話以網址中的 conversationId 為準，訊息會以該對話的聯絡人身分送出。成功時回應 HTTP 201，內容是剛送出的訪客訊息（type 為 incoming），不含 Agent 回覆。

Agent 回覆在背景產生。訪客可以用 GET /api/messages/?conversation={conversationId} 讀取對話訊息，不需帶驗證標頭。回應的 results 預設為最新 20 則訊息，依建立時間由舊到新排列；Agent 回覆的 type 為 outgoing。若尚未看到 Agent 回覆，稍後再讀取一次。

讀取交接關聯

對話資料中的 handoff 欄位提供關聯資訊。接續對話可取得 sourceConversationId 與 sourceTitle；原對話建立接續對話後，可取得 continuedToConversationId 與 continuedToTitle。整合端可用這些欄位提供「返回原對話」或「前往接續對話」入口。

權限與重送

匿名 Web Chat 訪客只能以原對話 UUID 操作仍有效的 Web Chat 對話；需要登入的 Web Chat 不接受匿名建立接續對話。已登入成員可操作其有權查看的組織對話，也可操作自己作為聯絡人的對話。整合端因逾時而重送同一摘要時，可以依 created 辨識是否取得仍存在的對話；已刪除的接續對話可以重新建立。