> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/serve/conversation-handoff-continuation.md).

# 對話交接與接續對話 API

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

當 Agent 在原對話產生交接摘要後，整合端可用摘要訊息建立接續對話。新對話沿用原對話的 Agent 與對話設定，後續訊息則送往新對話。以 API Key 串接的成員，一般對話的建立與送訊息方式請參考[建立對話與訊息](/tech/api-integration/conversations-and-messages.md)；匿名 Web Chat 訪客請改用[匿名 Web Chat 的後續傳訊](#anonymous-web-chat-messaging)。

API 回應的欄位名稱為 camelCase。

使用者在畫面上怎麼整理交接、接續到新對話，以及 Web Chat 要先開哪些設定（對話平台的「啟用對話交接」、Agent 的回覆模式需為 Agent），見使用者手冊的[對話交接](https://docs.maiagent.ai/work/maigpt/chat/conversation-handoff#enable-on-web-chat)。

## 建立接續對話 <a href="#create-continuation" id="create-continuation"></a>

交接只在 Web Chat 對話提供。匿名 Web Chat 訪客的原對話以 `POST /api/conversations/` 送出 `{"webChat": "<webChatId>"}` 建立，不需帶驗證標頭；`webChatId` 可在後台 Web Chat 設定頁取得（見[快速開始](/tech/serve/web-chat-sdk.md#quickstart)），回應的 `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/` 送出：

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

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

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

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

## 匿名 Web Chat 的後續傳訊 <a href="#anonymous-web-chat-messaging" id="anonymous-web-chat-messaging"></a>

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

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

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

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

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

## 讀取交接關聯 <a href="#read-handoff-links" id="read-handoff-links"></a>

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

## 權限與重送 <a href="#access-and-retry" id="access-and-retry"></a>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/serve/conversation-handoff-continuation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.