logo
Development
概要開発スペースワークスペースAPI Referenceベストプラクティス更新履歴
検索
日本語
開発スペース / エージェント / 有人チャットへの切り替え
有人チャット（ヒューマンハンドオフ）
最終更新日：約13時間前

有人チャット（ヒューマンハンドオフ）

有人チャット（ヒューマンハンドオフ）機能を利用することで、エージェント開発者はサードパーティのカスタマーサポートシステムと連携し、エージェントユーザーからの有人対応リクエストを処理できます。現在、Intercom、Livedesk、Livechat、Zoho Sales IQ、Sobot などのカスタマーサポートシステムとの連携に対応しているほか、Webhook または Custom Helpdesk（自社構築のカスタマーサポートシステム） を通じて、その他の有人対応システムをより柔軟に接続することもできます。

有人チャットの有効化方法

  1. エージェント設定 - 有人チャット で「有効化」ボタンをクリックし、ヒューマンハンドオフを有効にします。
  2. 必要なカスタマーサポートシステムを選択します（Intercom、Webhook、Livedesk、Custom Helpdesk（自社構築のカスタマーサポートシステム）などに対応）。
  3. 選択したサードパーティカスタマーサポートシステムの認証設定を完了し、メッセージ通信が正常に行えることを確認します（Custom Helpdesk は認証設定が不要です。詳細は「Custom Helpdesk」の設定を参照してください）。
  4. 企業の運用状況に合わせて、有人チャット関連の設定を調整します。
  5. エージェントの会話ウィンドウで有人チャットリクエストを発行し、正常に呼び出せることを確認します。

有人チャットのモード

有人チャット機能は、外部プラットフォーム→ヘルプデスク、ヘルプデスク→ヘルプデスク、Custom Helpdesk（自社構築のカスタマーサポートシステム） の3つのモードをサポートします。

モード ユーザーが会話を開始する場所 対応するオペレーター GPTBots の役割 適用シーン
外部プラットフォーム→ヘルプデスク エージェント連携がサポートする任意のチャネル（WhatsApp / iframe / Widget / Share / LINE など） 選択したサードパーティのヘルプデスクシステム（Intercom など） ユーザーの会話をヘルプデスクシステムに引き継ぎ、メッセージを双方向に転送 Intercom、Livedesk などのヘルプデスクプラットフォームをすでに利用しており、複数チャネルのユーザーをそのプラットフォームで一元的に対応したい場合
ヘルプデスク→ヘルプデスク そのヘルプデスクシステム自身のチャネル（Intercom プラットフォームなど） 同じヘルプデスクシステム そのプラットフォーム内の AI ボットとして動作し、有人対応への切り替え時にプラットフォームのオペレーターへ引き渡す ユーザーがもともとヘルプデスクプラットフォーム内で会話している場合
Custom Helpdesk（自社構築のカスタマーサポートシステム） お客様が自社構築したカスタマーサポートシステム自身のチャネル お客様の自社構築カスタマーサポートシステムのオペレーター AI の頭脳 + 会話のアーカイブのみを担当し、有人対応への切り替え時は API でシグナルを返すだけで、引き継ぎは代行しない お客様がすでに自社開発のカスタマーサポートシステムを持ち、ユーザーチャネルもオペレーターもお客様側にある場合

例として、ヘルプデスクシステムが Intercom の場合、前者 2 つのモードの違いは以下のとおりです：

flowchart TD
    A["ヒューマンハンドオフ機能"] --> B["外部→ヘルプデスク"] & C["ヘルプデスク→ヘルプデスク"]
    B --> D["エージェント連携チャネルからユーザーが会話開始"]
    D --> E["WhatsApp/Iframe/Widget/Share/LINE等"] & G["Intercomプラットフォーム"]
    E --> F["Intercomヘルプデスクが受信・処理"]
    G --> Q["Intercomシステムでは受信・処理不可"]
    C --> H["ヘルプデスクプラットフォームからリクエスト開始"]
    H --> I["Intercomプラットフォーム"] & K["非Intercomプラットフォーム"]
    I --> J["Intercomヘルプデスクが受信・処理"]
    K --> L["Intercomシステムでは受信・処理不可"]
     A:::Peach
     B:::Sky
     C:::Aqua
     D:::Sky
     E:::Sky
     G:::Sky
     F:::Sky
     Q:::Sky
     H:::Aqua
     I:::Aqua
     K:::Aqua
     J:::Aqua
     L:::Aqua
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D

Custom Helpdesk モードと前者 2 つのモードの根本的な違いは、GPTBots が会話の「引き継ぎ」を代行しなくなる点にあります。ユーザーチャネルもオペレーターももともとお客様のカスタマーサポートシステム内にあるため、GPTBots は質問への回答のみを担当し、有人対応への切り替えが必要になった際に Send Message API のレスポンスを通じて「有人対応に切り替えるべき」ことをお知らせします。その後のオペレーターの割り当てやメッセージ配信は、すべてお客様のシステム側で行います。

「外部→ヘルプデスク」認証の設定

エージェント連携モジュールがサポートする任意のプラットフォームからユーザーが有人対応をリクエストでき、選択したヘルプデスクシステムがこれを受信・処理します。例：

  • WhatsApp、iframe、Widget、Share、LINEなどでユーザーが会話を開始し、有人対応をリクエストした場合、Intercomヘルプデスクが受信・処理します。
  • Intercomプラットフォーム自体でリクエストした場合、このモードではIntercomヘルプデスクは受信・処理できません。

Intercom認証

Intercomによるヒューマンハンドオフの設定手順

  1. アプリ作成
    Intercomに登録し、ワークスペース作成を完了します。「アカウントアバター - 設定 - APPS & INTEGRATIONS」からDeveloper Hubページにアクセスし、「New app」でアプリを作成します。既存アプリがある場合は対象アプリを選択して設定ページへ進みます。
    alt text
  2. AccessToken取得とGPTBotsへの入力
    • 「Authentication」メニューでAccess tokenをコピーします。
      intercom Access token
    • 「ヒューマンハンドオフ - Intercom認証」のAccess token入力欄に貼り付けます。
      alt text
    • IntercomのWebhookメニューで「GPTBotsメッセージ受信アドレス」をEndpoint URLに設定します。
      alt text
    • WebhookのTopicsで下記4イベントを購読し、「save」で保存します。
      • conversation.admin.closed
      • conversation.admin.replied
      • conversation.admin.snoozed
      • conversation.read

これでIntercomの設定は完了です。エージェント会話ウィンドウでヒューマンハンドオフをリクエストすると、Intercomヘルプデスクがユーザーのメッセージを受信します。返信すると有人チャットが開始されます。

Livedesk認証

  1. Livedesk開発者コンソールにログインします。
  2. Livedesk製品にアクセスし、「プロジェクト設定 - API管理 - APIキー」ページを選択して、APIキーとAPIシークレットをコピーします。
    Livedeskキー
  3. プロジェクトキーを「GPTBots - 人間による対応 - Other to Livedesk」のアクセストークン入力欄に貼り付け、保存すると認証設定が完了します。
    Livedesk有人対応認証

Webhook認証

Webhook経由でヒューマンハンドオフを提供する手順

  1. サーバー環境でWebhook受信サービスを構築し、下記3つのインターフェースを提供します。詳細はヒューマンハンドオフサービス - Webhookを参照してください。
    • セッション作成: /conversation/establish
    • チャット: /chat
    • セッション終了: /conversation/close
  2. エージェントのヒューマンサービス設定でWebhook受信サービスのURL、ユーザー名、パスワードを設定します。
    alt text

    URLアドレス：必須。エージェント側からのメッセージ受信用
    ユーザー名・パスワード：任意。Webhookサービスの仕様に従う

  3. 「エージェント-インテグレーション-API」でAPI機能を有効化し、GPTBotsメッセージ受信アドレスをWebhookの送信先URLに設定します。詳細はヒューマンハンドオフサービス - Webhookを参照。
    alt text
    これでWebhook認証設定は完了です。エージェントチャットウィンドウでヒューマンサービスをリクエストできます。

Webhook と Custom Helpdesk の違い：Webhook モードでは、GPTBots が引き続き有人セッションを自ら作成し、ユーザーメッセージをお客様の /chat インターフェースにプッシュします。オペレーターの返信は API を通じてエージェントの会話ウィンドウに返され、待機タイムアウトやセッションタイムアウトなどの仕組みもすべて有効です。「ユーザーは GPTBots のチャネル（Widget / WhatsApp など）で会話し、オペレーターはお客様自身のシステムにいる」というシーンに適しています。Custom Helpdesk モードでは、GPTBots はメッセージを一切自らプッシュせず、API レスポンスで有人対応への切り替えシグナルを返すだけです。「ユーザーもオペレーターもお客様自身のシステム内にいる」というシーンに適しています。

livechat認証

  1. livechatアカウント作成し、organization_idを取得します。
    image-20241022201522994
  2. APPを作成し、Blocks追加、App認証をサーバーサイドアプリに設定。clientIdを取得します。APP作成
    image-20241022201629843
    image-20241022201639199
    image-20241022201648672
  3. APP webhookにGPTBotsメッセージ受信アドレスをwebhook urlとして設定します。
    image-20241022201729792
  4. Chat webhookにGPTBotsメッセージ受信アドレスを設定し、incoming_eventとchat_deactivatedを選択します。
    image-20241022201849040
    image-20241022201857586
  5. Private InstallationでAPPをインストールします。
    image-20241022202514528
  6. 取得したorganization_idとliveChatClientIdを入力し、設定を完了します。
    image-20241022202903285

Sobot認証

Sobot連携設定を参照してください。SobotヒューマンサービスはSobotウィジェットのみ対応です。

Zoho Sales IQ認証

  1. ZohoアカウントでZoho API Consoleにログインします。

    ※米国以外のアカウントはドメイン切替が必要です。詳細は前提条件 - Org OAuthトークン生成を参照。

  2. Homepage URLにサービスドメイン、Authorized Redirect URIsに「サービスドメイン+/api/console/bot/zoho/salesiq/org/redirect」を入力し、CREATEをクリック。Client IDとClient Secretをコピーします。
    image-20250508145401316
  3. GPTBotsでClient ID・Client Secret・Screen Name・サーバーリージョンを入力し、認証をクリック。
  4. 認証後、ポップアップでAcceptをクリックします。
  5. Public KeyはWebhookのセキュリティ設定を有効化する場合のみ入力します。詳細はZoho Sales IQ連携設定を参照。
  6. 適切なZoho有人サポートグループを選択します。
    image-20250508161142022

    ※このシナリオでは、Zoho側から送信されたファイルはボット側で受信できません。

有人チャットの設定

  1. 有人チャット
    alt text
    サービス状態：サードパーティ有人チャットシステムの利用可否を表示
    • 未設定：認証情報未入力
    • 利用可能：認証情報が正常に検証済み
    • 利用不可：認証情報が無効・失敗
      トリガータイミング：カスタムトリガー説明を設定可能
  2. タイムアウト機構
    タイムアウト待機：デフォルト60秒。ユーザーがリクエスト後の最大待機時間。超過時は終了または継続を促します。
    セッションタイムアウト：デフォルト180秒。有人対応者の最終メッセージ後、N秒間ユーザー応答がなければ自動終了。
  3. 有人チャット対応時間
    alt text
    最大10件までカスタム設定可能
    • 週間：曜日ごとに時間帯を設定し、毎週繰り返し
    • カスタム：日付指定で一度だけ実行
      複数時間帯がある場合：
    • 当日の「有人対応時間」ルールを抽出
    • 最も広い時間帯で重複ルールを計算。重複しない場合は個別に有効
    • 複数の非重複最大ウィンドウがあれば、その分有効時間帯が発生

      例：2024年12月12日に09:00~12:00、10:00~12:00、13:00~18:00、15:00~17:00が設定されている場合、有効時間帯は09:00~12:00、13:00~18:00

  4. 対応時間外の返信
    対応時間外は「プリセットテキスト」で自動返信
  5. 会話内容の引き継ぎ
    サードパーティサービス呼び出し時、Nラウンドの履歴＋最新質問を送信

注意：Custom Helpdesk（自社構築のカスタマーサポートシステム） を選択した場合、GPTBots は有人セッションを作成せず、メッセージも配信しないため、上記のタイムアウト機構、有人チャット対応時間、会話内容の引き継ぎはいずれも適用されません。有人対応への切り替えリクエストは常に成功を返し、待機、キューイング、対応時間外などのロジックはお客様のカスタマーサポートシステム側で処理する必要があります。

有人チャットリクエストの発行

  1. ユーザーが有人チャットをリクエスト
    ユーザーが有人対応を希望した場合、LLMがヒューマンハンドオフを呼び出すか判断します。呼び出す場合、ツールを実行しメールアドレス入力を促します。既にメール情報がある場合は省略されます。
    alt text
    • ログイン済みかつメール認証済みの場合、システムがメール情報を保持
    • バブルコンポーネントでwindow.ChatBot.setEmail("somebody@mail.com")を実行した場合、メール情報を保持
    • iframeでiframe_url?email=somebody@mail.comを指定した場合、メール情報を保持
  2. サードパーティ有人チャットシステムがユーザーのメッセージを受信し、最初の返信を行うとセッションが開始されます。
  3. ユーザーと有人対応者は無制限にメッセージをやり取りでき、どちらからでも会話を終了できます。

Intercom、Webhook、LiveChatなど、あらゆるサードパーティカスタマーサポートシステムと連携可能です。上記機能はすべて適用されます。
Custom Helpdesk（自社構築のカスタマーサポートシステム）モードでは、手順 2、3 はお客様のカスタマーサポートシステム側で実装します。GPTBots は手順 1 で有人対応への切り替えが成功した際に API でシグナルを返すことのみを担当します。詳細は以下を参照してください。

「ヘルプデスク→ヘルプデスク」認証の設定

このモードでは、ヘルプデスクプラットフォームからのみ有人対応リクエストが可能で、同じヘルプデスクシステムが対応します。例：

  • Intercomプラットフォームでリクエストした場合、Intercomヘルプデスクが対応
  • 非Intercomプラットフォームからのリクエストは対応不可

Intercom to Intercom

設定手順はIntercom連携ガイドを参照してください。

Zoho Sales IQ to Zoho Sales IQ

Zoho Sales IQ連携設定を参照してください。

※このシナリオではOpenAI-GPT-4o-miniの制約により、有人対応が呼び出せない場合があります。他モデルの利用を推奨します。

Livechat to Livechat

Livechat連携ガイドを参照してください。

Livedesk to Livedesk

Livedesk連携ガイドを参照してください。

「Custom Helpdesk」（自社構築のカスタマーサポートシステム）の設定

すでに自社開発のカスタマーサポートシステムをお持ちの企業向けのモードです。エンドユーザーもオペレーターもお客様のシステム内にあり、「AI による回答」の部分のみを GPTBots に任せます。このモードでは、GPTBots は有人セッションを作成せず、メッセージを自ら配信しません。有人対応への切り替えが必要になった際にメッセージ送信 API のレスポンスでシグナルを返すだけで、オペレーターの割り当てとメッセージ配信はお客様のシステム側で行います。

設定手順

  1. エージェント設定 - 有人チャットで「有効化」をクリックし、カスタマーサポートシステムとして Custom Helpdesk を選択します。認証情報の入力は不要で、「確定」をクリックするだけで完了します。
  2. 「エージェント-インテグレーション-API」で API 機能を有効化し、API Key を取得します。
  3. 必要に応じて「トリガータイミング」を設定します。FlowAgent の場合は、有人チャットノードで「オペレーター向け備考テンプレート」を設定でき、引き継ぎ備考としてお客様のシステムに返されます。

利用フロー

すべてのやり取りは メッセージ送信 API を通じて行います：

  1. 通常の会話：role=user でメッセージ送信 API を呼び出すと、エージェントが通常どおり返信します。
  2. 有人対応切り替えシグナルの受信：エージェントが有人対応への切り替えをトリガーすると、レスポンスに human_trigger: true と引き継ぎ備考 handoff.note が返されます（ストリーミングの場合は code 36 / 107 のフレーム）。お客様のシステムはこれに基づいて会話をオペレーターに割り当てます。備考はオペレーターの参考用であり、ユーザーには表示しないでください。
  3. メッセージのアーカイブ：有人対応中は、オペレーターの返信を role=human_agent（human_agent_info でオペレーター情報を付加可能）で送信し、ユーザーメッセージは ai_response: false を渡すか、または省略します。これらのメッセージはアーカイブのみ行われ、AI をトリガーせず、クレジットも消費しません。
  4. AI への引き戻し：オペレーターの対応が終了したら、次のユーザーメッセージで ai_response: true を渡すと、会話は AI による通常の応答に戻ります。

注意：

  • このモードでは、タイムアウト機構、有人チャット対応時間、会話内容の引き継ぎはいずれも適用されず、有人対応への切り替えリクエストは常に成功を返します。
  • オペレーターの対応終了後に ai_response: true を渡し忘れると、その会話は「アーカイブのみ」の状態のままとなり、ユーザーは AI の返信を受け取れません。
  • ユーザーが GPTBots のチャネル（Widget / iframe / WhatsApp など）で会話し、オペレーターのみがお客様のシステムにいる場合は、Webhook認証を使用してください。