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 for creating regular conversations and sending messages; anonymous Web Chat visitors should use Subsequent Messaging for Anonymous Web Chat Visitors.

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 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": "<webChatId>"} to POST /api/conversations/ without an authentication header. You can obtain webChatId from the Web Chat settings page in the admin console (see 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 <your 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/:

{"summaryMessageId": "<UUID of the handoff summary message in the original conversation>"}

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/

{"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.