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 から任意の会話を引き継げます

Topic-based Routing は、会話のトピックに基づいて handoff を特定のオペレーターにルーティングする高度な機能です。各ルーティングプロファイルは、トピック、適用される状況の説明、そのトピックを担当するオペレーターのリストを定義します。handoff がトリガーされると、AI は会話を最も関連性の高いルーティングプロファイルにマッチさせ、割り当てられたオペレーターに通知します。ルーティングプロファイルは、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 を適切なオペレーターに振り分けます。

handoff がトリガーされると、AI はすべてのアクティブなルーティングプロファイルに照らして会話を評価し、最も関連性の高いトピックにマッチさせます。そのプロファイルに記載されたオペレーターに通知が送られます。マッチするルーティングプロファイルがない場合は、デフォルトの通知動作（settings.emails のメールリスト）が使用されます。

例： ファイナンスチームに割り当てた「Billing」ルーティングプロファイルと、エンジニアに割り当てた「Technical Support」プロファイルがあるとします。顧客が請求書について尋ねて handoff をトリガーすると、AI は会話を「Billing」にマッチさせ、エンジニアではなくファイナンスチームのみに通知します。

ルーティングプロファイルは、Dashboard の Handoff > Topic-based Routing で設定するか、PUT request の routing_profiles 配列経由で設定します。

Field	Description
id integer	ルーティングプロファイルの ID
name string	トピック名（例：「Billing」、「Technical Support」）（最大 100 文字）
description string	このプロファイルがいつマッチすべきか。これらのオペレーターにルーティングすべき会話のタイプを記述します（最大 2000 文字）
is_active boolean	このルーティングプロファイルが有効かどうか
user_ids array of integers	このプロファイルがマッチしたときに通知すべきオペレーターの ID

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 で送り返してください。

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 を返します。

---