> 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/en/serve/conversation-handoff-continuation.md).
# Conversation Handoff and Continuation API
Create a continuation conversation from a handoff summary and identify the relationship between the original and continuation conversations.
After an Agent generates a handoff summary in the original conversation, your integration can use the summary message to create a continuation conversation. The new conversation inherits the original conversation's Agent and conversation settings. Send subsequent messages to the new conversation. For members integrating with an API Key, see [Create Conversations and Messages](/tech/en/api-integration/conversations-and-messages.md) for creating regular conversations and sending messages; anonymous Web Chat visitors should use [Subsequent Messaging for Anonymous Web Chat Visitors](#anonymous-web-chat-messaging).
API response field names use camelCase.
For instructions on preparing a handoff in the UI, continuing in a new conversation, and the settings required for Web Chat (enable “Enable conversation handoff” on the conversation platform and set the Agent's reply mode to Agent), see [Conversation Handoff](https://docs.maiagent.ai/work/maigpt/chat/conversation-handoff#enable-on-web-chat) in the user manual.
## Create a Continuation Conversation
Handoff is available only for Web Chat conversations. To create the original conversation for an anonymous Web Chat visitor, send `{"webChat": ""}` to `POST /api/conversations/` without an authentication header. You can obtain `webChatId` from the Web Chat settings page in the admin console (see [Quickstart](/tech/en/serve/web-chat-sdk.md#quickstart)). The `id` in the response is the original conversation's UUID.
First, retrieve the original conversation with `GET /api/conversations/{conversation_id}/`. Anonymous visitors do not need an authentication header. For members integrating with an API Key, both this GET request and the `POST` request below to create a continuation conversation require `Authorization: Api-Key `. If `handoff.enabled` in the response is `false`, conversation handoff is disabled on the platform and no handoff summary will be generated. When it is `true`, after the Agent generates a handoff summary, `handoff.latestSummaryMessageId` provides the summary message's UUID. An empty field means the original conversation does not yet have a handoff summary: a summary is generated only when the user requests a handoff in the original conversation (for example, by sending “prepare a handoff,” “continue in a new conversation,” or “handoff,” or clicking “Prepare handoff” in the prompt bar), or when the Agent proposes a handoff due to high context usage and the user agrees. Only Agents in Agent or Team mode generate summaries. Retrieve the original conversation again after the summary is generated to obtain its ID. Then send the following to `POST /api/conversations/{conversation_id}/handoff-continuations/`:
```json
{"summaryMessageId": ""}
```
`summaryMessageId` must refer to a handoff summary in this original conversation. The first creation returns HTTP 201. While the continuation conversation still exists, resubmitting the same summary returns the existing conversation with HTTP 200. If the previous continuation conversation has been deleted, resubmitting can create a new conversation and return HTTP 201. Both responses include:
| Field | Meaning |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `conversationId` | UUID of the continuation conversation |
| `title` | Title of the continuation conversation |
| `created` | `true` means a new conversation was created in this request; `false` means an existing conversation was retrieved |
The request is rejected if the message does not belong to the original conversation or is not a handoff summary. Your integration should save the returned `conversationId` and use it for subsequent messages.
## Subsequent Messaging for Anonymous Web Chat Visitors
Anonymous Web Chat visitors have no API Key and cannot use `POST /api/messages/`. After obtaining the continuation conversation's `conversationId`, use the Web Chat message endpoint without an authentication header:
```
POST /api/conversations/{conversationId}/web-chat-messages/
```
```json
{"content": "A follow-up to the previous question"}
```
The `conversationId` in the URL determines the conversation. The message is sent as that conversation's contact. On success, the endpoint returns HTTP 201 with the visitor message just sent (`type` is `incoming`), without the Agent's reply.
The Agent generates its reply in the background. Visitors can retrieve conversation messages with `GET /api/messages/?conversation={conversationId}` without an authentication header. By default, `results` contains the latest 20 messages, ordered by creation time from oldest to newest. Agent replies have `type` set to `outgoing`. If the Agent's reply is not yet visible, retrieve the messages again later.
## Read Handoff Relationships
The `handoff` field in conversation data provides relationship information. A continuation conversation exposes `sourceConversationId` and `sourceTitle`. After a continuation conversation is created, the original conversation exposes `continuedToConversationId` and `continuedToTitle`. Your integration can use these fields to provide “Return to original conversation” or “Go to continuation conversation” links.
## Access and Retries
Anonymous Web Chat visitors can use the original conversation UUID to operate only on Web Chat conversations that are still valid. Web Chat configurations that require login do not allow anonymous creation of continuation conversations. Logged-in members can operate on organization conversations they are authorized to view, as well as conversations in which they are the contact. If your integration resubmits the same summary after a timeout, use `created` to determine whether an existing conversation was retrieved. Deleted continuation conversations can be recreated.
---
# 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/en/serve/conversation-handoff-continuation.md?ask=&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.