Handoff Configuration

Human Handoff を使うと、AI Agent が個別の対応を必要とする状況を検出したときに、会話を人間のオペレーターに自動的に転送できます。Handoff は AI 主導 です。AI は設定可能なガイドラインに照らして会話を継続的に評価し、適切なときに、手動の介入なしで handoff をトリガーします。

自動 handoff の仕組み:

1. 会話中、AI は各メッセージを generic guidelines（例：ユーザーの不満、知識の不足）と、定義した custom guidelines に照らして評価します
2. ガイドラインがトリガーされると、AI は訪問者に人間と話したいかどうかを尋ねる確認メッセージを表示します
3. 訪問者が確認すると、会話は人間のオペレーターに転送され、必要に応じてこれまでの会話の AI 生成サマリーが付けられます
4. 営業時間が設定されていて、リクエストがその時間外の場合は、代わりにカスタムメッセージが表示されます

追加の handoff メソッド:

• Keyword triggers — 訪問者は特定のフレーズ（例：「speak to human」、「agent」）を入力して、直接 handoff をリクエストできます
• Manual handoff from Dashboard — オペレーターは、会話の担当者を変更することで、Inbox から任意の会話を引き継げます

トピックベースのルーティングでは、AI がチームメンバーのルーティング説明に基づいて、そのメンバー 1 人に handoff を割り当てることができます。各プロファイルは 1 人のユーザーに属し、インサイトのトピックカテゴリとは別のものです。プロファイルは PUT リクエストの routing_profiles で設定します。担当者の割り当てとメール通知の宛先は、別々の設定です。

Get Handoff Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

レスポンスには複数のネストされたオブジェクトが含まれます：

settings — handoff のコア設定：

Field	Description
is_active boolean	human handoff が有効かどうか
keywords array of strings	handoff を促すトリガーキーワード（例：["speak to human", "agent"]）
ai_summary_active boolean	handoff が発生したときに、AI が生成した会話サマリーを人間のオペレーターに送信します
topic_based_routing_active boolean	特定のオペレーターへのトピックベースルーティングが有効かどうか（読み取り専用、ルーティングプロファイルで設定）
question_message string	人間につなぐかどうかを訪問者に尋ねるために表示されるメッセージ
confirmation_message string	訪問者が handoff を確認した後に表示されるメッセージ（最大 500 文字）
confirmation_outside_working_hours_message string	営業時間外に handoff がリクエストされたときに表示されるメッセージ（最大 500 文字）
working_hours_active boolean	handoff を営業時間内のみに制限します
timezone string	営業時間のタイムゾーン（例："Europe/London"）
send_email_notification boolean	handoff 時にオペレーターにメール通知を送信します
emails array of strings	通知先のメールアドレス

availability — 営業時間のスケジュール（スロットの配列）：

Field	Description
id integer	営業時間スロットの ID
day_span string	曜日または曜日範囲（例："monday"、"monday-friday"）
start_time string	"HH:MM" 形式の開始時刻
end_time string	"HH:MM" 形式の終了時刻

generic_guidelines — 事前定義された handoff トリガールール（配列）：

Field	Description
name string	ガイドラインのタイプ："user_frustration"、"customer_support_suggestion"、"lack_of_knowledge"、"irrelevant_advice"、"media_message"
description string	このガイドラインがトリガーされるタイミングの説明
is_active boolean	このガイドラインが有効かどうか

custom_guidelines — ユーザー定義の handoff トリガールール（配列）：

Field	Description
id integer	ガイドラインの ID
name string	カスタムガイドライン名（最大 100 文字）
description string	このガイドラインがいつ handoff をトリガーすべきか（最大 2000 文字）
is_active boolean	このガイドラインが有効かどうか

routing_profiles — Topic-based routing は、会話の内容に基づいて handoff を適切なオペレーターに振り分けます。

AI が handoff を開始するとき、有効なルーティングプロファイルからチームメンバーを選択できます。選択が有効であれば、そのユーザーに会話が割り当てられます。それ以外の場合は未割り当てのままです。別の条件で handoff が開始された場合も、未割り当てになることがあります。メール通知には、ルーティングでの選択とは独立して settings.send_email_notification と settings.emails が使われます。

例： 経理担当のメンバーに「Billing and invoice questions」、エンジニアに「Technical support」というルーティング説明を設定します。請求書に関する質問では、AI が経理担当のメンバーに handoff を割り当てることができます。この割り当てによって、設定済みのメール通知先一覧が変わることはありません。

プロファイルは アクションとMCP > 人間への引き継ぎ > 編集アクション > トピックベースのルーティング、または PUT リクエストで設定します。

Field	Description
user_id integer	チームメンバーのユーザー ID。この AI Agent へのアクセス権を持つユーザーである必要があります
routing_description string	このメンバーが担当すべき会話の説明（最大 150 文字。有効時は空にできません）
is_active boolean	このルーティングプロファイルが有効かどうか
email, first_name, last_name strings	GET で返されるユーザー情報。PUT では必須ではありません

Update Handoff Configuration

Scope: write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

注意

PUT は handoff 設定全体をアトミックに置き換えます。settings、availability、generic_guidelines、custom_guidelines を含めてください。ルーティングを保持するには routing_profiles も含めてください。省略すると空のリストがデフォルトとして使われ、既存のプロファイルが削除されます。部分的な変更を行うには、まず現在の設定を GET し、必要なフィールドを変更してから、完全なオブジェクトを PUT で送り返してください。各ルーティングプロファイルでは user_id、routing_description、is_active を使用します。

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

Response 200 OK — 更新された handoff configuration を返します。

---