Handing off conversations within Kustomer Chat

Conversation Handoff

SDK Feature | 2026-02-16

Create a new Kustomer Chat conversation and import up to 100 historical messages in one API call.

What is Conversation Handoff?

When creating a new Kustomer Chat session, Conversation Handoff also creates and imports an existing message history without the need for an additional request.

Use it when you want to:

• Continue a conversation that began in your AI or bot.
• Migrate a conversation from an external chat system.
• Move a resolved thread into Kustomer for visibility or compliance.
• Avoid creating a session and sending messages one by one.

The SDK handles customer authentication automatically using the current tracking token. You do not pass the tracking token manually.

Expected behavior

• Creates a session and loads historical messages in one request.
• Preserves chronological message history.
• Applies brand, language, and external identifiers at creation time.
• Returns the created conversation so you can immediately open it in the UI.

Technical Details

• The server sorts messages by date. Order of submission does not matter.
• The request must include:
  • Minimum 2 messages.
  • At least 1 inbound (in) message.
  • At least 1 outbound (out) message.
• Maximum 100 messages per request.
• active: true creates an open conversation.
• active: false creates a closed conversation.
• All outbound messages display the value provided in the from field.
• Empty or invalid message bodies may be rejected.

APIs changed: No
New fields introduced: None (SDK-level feature)

Benefits to Your App

After implementing Conversation Handoff:

• Users see the full prior conversation immediately.
• Agents retain context without manual transcript copying.
• AI-to-agent transitions feel seamless.
• Migration workflows require only one API call instead of multiple.

Recommended Action

Upgrade or implement Conversation Handoff if you:

• Use AI or bots before routing to Kustomer Chat.
• Import conversations from another messaging platform.
• Need a single-step migration flow.
• Want to eliminate manual message replay.

No migration is required for existing chat flows unless you want consolidated session creation.

Minimal Request Example

All chat SDKs use the same logical request structure:

1. Start the SDK.
   Ensure the SDK is initialized and chat is enabled before calling handoff.
2. Construct the message array.
   Create an array of HandoffMessage objects. Each message must include:
   1. date (ISO 8601 format)
   2. direction (in or out)
   3. body (string)
3. Call Kustomer.handoff(...).
   Pass the required parameters:
   1. active
   2. from
   3. messages
4. Optionally include:
   1. brand
   2. externalId
   3. lang
5. Handle the response.
   On success, use the returned session or conversation object to open or display the conversation in your UI.

Conceptual request body:

{
  "active": false,
  "from": "66ad363c984ba5001fbf9e34",
  "messages": [
    { "date": "2026-01-22T14:35:00Z", "direction": "in", "body": "Hello" },
    { "date": "2026-01-22T14:36:00Z", "direction": "out", "body": "Hi there!" }
  ],
  "brand": "brand-123",
  "externalId": "ext_12345",
  "lang": "en"
}

Request Parameters

Message Object

Each message must include:

Message Rules

• Minimum: 2 messages.
• Maximum: 100 messages.
• At least one in and one out.
• Messages may be sent in any order; server sorts by date.
• Invalid timestamps or empty bodies may cause rejection.

Implementing this endpoint using the iOS SDK

let messages: [KUSHandoffMessage] = [
  KUSHandoffMessage(date: "2026-01-22T14:35:00Z", direction: .inbound, body: "Hello, I need help with my order"),
  KUSHandoffMessage(date: "2026-01-22T14:36:00Z", direction: .outbound, body: "Hi! I'd be happy to help.")
]

Kustomer.handoff(
  active: false,
  from: "agent-123",
  messages: messages,
  brand: "brand-123",
  externalId: "ext_12345",
  lang: "en"
) { session, error in
  if let session = session, let id = session.id {
    Kustomer.openConversation(id: id) { _ in }
  }
}

After Handoff

Each SDK returns the created conversation. You can:

• Open the conversation immediately.
• Store the conversation ID for later retrieval.
• Route the user directly into the Kustomer Chat UI.

Technical Notes

• The backend enforces message limits.
• Server default sorts by ISO timestamp.
• Authentication relies on the active tracking token in the SDK session.
• Handoff creates a new conversation. It does not append to an existing conversation.
• Errors may occur if validation rules are violated.

Errors and Troubleshooting

A 2xx response indicates the handoff succeeded.

Any non-2xx response indicates a failure. The response includes an error description explaining the reason for the failure.

Common validation errors include:

• Exceeding the maximum of 100 messages.
• Providing fewer than 2 messages.
• Missing required message fields (date, direction, or body).
• Failing to include at least one in and one out message.
• Providing an invalid ISO 8601 timestamp.

Review the error description in the response body to determine the exact cause.

Example: 400 Bad Request — Too Many Messages

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": 400,
  "error": "too_many_messages",
  "message": "Maximum 100 messages allowed per handoff request.",
  "details": {
    "maxAllowed": 100,
    "received": 142
  }
}

Example: 422 Unprocessable Entity — Direction Rule Violation

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "status": 422,
  "error": "direction_requirement_failed",
  "message": "Handoff requires at least one 'in' and one 'out' message.",
  "details": {
    "inboundCount": 2,
    "outboundCount": 0
  }
}