会話の引き継ぎと継続 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 のみです。生成後に元の会話を再取得すると、サマリーの ID を取得できます。続いて 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": "前の質問の続きです"}

URL 内の 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 によって、まだ存在する会話を取得したかどうかを判断できます。削除された継続会話は再作成できます。