logo
Development
概要開発スペースワークスペースAPI Referenceベストプラクティス更新履歴
検索
日本語
開発スペース / エージェント / インテグレーション / Zoho Sales IQ
Zoho Sales IQ
最終更新日：約8時間後

Zoho Sales IQ

Zoho Sales IQ にエージェントサービスを連携することで、Zoho Sales IQ のユーザーが Zoho Sales IQ を通じてエージェントとやり取りできるようになります。

準備

連携を行う前に、Zoho 側でいくつかのパラメータを設定する必要があります。これらのパラメータは、GPTBots との連携時に使用されます。

Client ID の作成

  1. Zoho API Console にログインします。

    注：アカウントが米国（US）以外のデータセンターに属している場合は、ドメインを変更する必要があります。詳細は以下をご参照ください。

    データセンター 開発者コンソール URL
    US (United States) https://api-console.zoho.com/add
    EU(Europe) https://api-console.zoho.eu/add
    IN(India) http://api-console.zoho.in/add
    AU(Australia) http://api-console.zoho.com.au/add
    CN(China) http://api-console.zoho.com.cn/add
    JP(Japan) http://api-console.zoho.jp/add

  2. 既に利用可能なアプリケーションがある場合は、そのアプリケーションに移動し、「Client Secret」をクリックして、該当の Client ID と Client Secret をコピーしてください。これらは GPTBots のインテグレーション設定時に使用します。

    image-20250507153254209

  3. まだ利用可能なアプリケーションがない場合は、右上の ADD CLIENT をクリックし、アプリケーションのタイプに応じて適切なクライアントを作成します。

    image-20250507153127149

    image-20250507153459912

  4. 新しいアプリケーションを作成する場合は、「Homepage URL」にご利用中のサービスのドメイン名を入力し、「Authorized Redirect URIs」には、現在のサービスのドメイン名 + /api/console/bot/zoho/salesiq/redirect を入力して CREATE をクリックします。作成に成功すると、システムが Client ID と Client Secret を発行します。これらをコピーして、GPTBots のインテグレーション設定に使用してください。

    image-20250507160039517

注：1 つの Client ID は、同時に最大 20 件までの認証が可能です。20 件を超えると、最初に認証されたエージェントの Zoho 認証が無効になります。

インテグレーション設定

  1. GPTBots にログインします。

  2. 組織に入り、該当するエージェントを選択し、バージョンを保存して Publish をクリックします。公開に成功したら、Integrations をクリックします。

    image-20250225121541516

  3. インテグレーション方法として Zoho Sales IQ を選択します。

    image-20250507163753173

  4. 各種パラメータを入力します。

    • Client ID と Client Secret：必須。準備フェーズで取得したものを入力してください。
    • Screen Name：必須。ログイン中のアカウントページの URL から取得します。ドメインの直後にある最初の path 文字列を使用してください。たとえば https://salesiq.zoho.com/gptbos/mychats/000000000000003 というアドレスであれば、「gptbots」が Screen Name になります。
    • Email：必須。Zoho アカウントのプロフィールに紐づいているメールアドレスを入力してください。
    • Server Region：ご利用の Zoho アカウントが属するリージョンを選択してください。
    • Public Key：任意。後述の Webhook 設定で「Secure your webhook」を有効化する場合は、先に Integation をクリックしてから戻って入力してください。有効にしない場合は不要です。

    image-20250507164140213

  5. Integration をクリックすると、認可ステータスのポップアップが表示されます。Accept をクリックしてください。

    image-20250507165858728

  6. 認可に成功すると、GPTBots により Webhook URL が生成されます。この段階で、Setting ページへ移動します。

    image-20250507172323517

  7. Workflows - Data Workflows の順に進み、右上の Add（View） をクリックします。

    説明：一部のアカウントバージョンでは、この入口が Webhooks - Data modifications と表示されますが、両者の機能は同じです。

    alt text

    alt text

    alt text

  8. Webhook の内容を入力します。

    • Brand：Workflows（Webhook）を受信する対象のブランドを選択します。訪問者が実際に使用しているブランドと必ず一致させてください。つまり、Web サイトに埋め込んだウィジェットのインストールコードが属するブランドです。ここで誤ったブランドを選択すると、その会話で発生したイベントはこの Workflow をトリガーせず、GPTBots にメッセージがまったく届かない状態になります。

    • Module：Conversation を選択します。

    • URL to be invoked：GPTBots のインテグレーション設定で取得した Webhook URL を入力します。必ずインテグレーション設定ページから直接コピーし、他の環境のアドレスを流用しないでください。流用すると、メッセージが別の環境へ送信されてしまいます。

    • Events：conversation.created と conversation.visitor.replied を必ず両方チェックしてください。どちらか一方でも欠けてはいけません。

      • conversation.created：新しい会話が作成された際に GPTBots へ通知され、GPTBots はこれをもとにその会話を引き受け（pick up）ます。
      • conversation.visitor.replied：訪問者のその後の各メッセージの通知です。GPTBots はこのイベントを処理する際に会話の帰属を検証します。conversation.created が欠けているために引き受けが完了していない場合、訪問者のその後のメッセージはすべて破棄されます。

      その他のイベントタイプは GPTBots では処理されないため、チェックしても効果はありません。

    • Action：Webhook を選択します。

    入力が完了したら Create webhook をクリックします。

    alt text

    ⚠️ 注意：ここでの Webhook URL には、必ずインテグレーション設定ページで生成された Webhook URL を入力してください。これは「人工サービス - Other to Zoho Sales IQ」シナリオで使用するコールバックアドレス（/api/console/human/callback/zoho/salesiq/event）とは別のアドレスであり、両者の用途は異なります。混同するとメッセージが破棄されます。両方のシナリオを使用する場合は、それぞれ別の Data Workflow を作成してください。

  9. Secure your webhook：任意のステップです。Webhook のセキュリティ（正規の送信元からのリクエストであり、偽造されたものではないか）を検証するかどうかを選択できます。有効化後、public key の生成をクリックし、「In Use」マークの付いた public key をコピーして、GPTBots のインテグレーション設定ページに入力してください。

    image-20250507173308438

Zoho Sales IQ 上でエージェントと会話する

インテグレーション設定が完了すると、Zoho のサービス上でエージェントと会話できるようになります。
image-20250507182819135

よくある質問

1. 会話を作成できず、Live chat has been disabled と表示される

Zoho 側で該当ブランドのライブチャット機能が無効になっている場合、Zoho は会話の作成を拒否し、このエラーを返します。以下を確認してください。

  1. Settings - Brands に進み、対象ブランドのステータスが Active（リスト右端のスイッチがオン）になっていることを確認します。ブランドが無効化されている場合、その配下のすべての会話は作成できません。
  2. 該当ブランドの Configurations - Channels に進み、Live chat のスイッチがオンになっていることを確認します。
  3. 選択した部門（Department）が無効化されていないことを確認します。

Configurations 内に Live chat のスイッチが見つからない場合は、通常 Zoho アカウントのプラン側でこの機能が無効化されているため、Zoho 公式サポートへお問い合わせください。

2. Zoho ウィジェットからメッセージを送ると、Zoho のサポートデスクには届くが、エージェントがまったく返信しない

まず前提を理解してください：GPTBots は Zoho の Webhook を受信すると、即座に成功を返してから非同期で処理します。そのため、メッセージが GPTBots 側で破棄されていても、Zoho の Data Workflows リストの Failures は 0 のままであり、Failures で問題の有無を判断することはできません。唯一有効な判断材料は Last Triggered 列です。

ステップ 1：Last Triggered でどちら側の問題かを切り分ける

Settings - Workflows - Data Workflows に進み、インテグレーションの Webhook URL を指している Workflow を見つけて、Last Triggered を確認します。この列に表示されるのは Zoho アカウントのタイムゾーンでの時刻であり、お使いのローカル時刻と数時間ずれている場合があるため、換算してから比較してください。

  • 空欄、または先ほどメッセージを送った時刻ではない → Zoho がそもそもリクエストを送信していないため、問題は Zoho 側にあります（下記 A を参照）。
  • まさに先ほどメッセージを送った時刻 → リクエストは送信済みのため、問題は GPTBots 側の処理条件にあります（下記 B を参照）。

A. Zoho 側：Workflow がトリガーされていない

  1. その Workflow の右端のスイッチが ENABLED（緑色）の状態であること。

  2. Brands に訪問者が実際に使用しているブランドが含まれていること。該当の会話を開くと、会話詳細ページの上部にそのブランド名が表示されるので、それと照合してください。これが最も多い原因です：ウィジェットは A ブランドで設置されているのに、Workflow は B ブランドに紐づいており、イベントが永遠にトリガーされないケースです。

  3. Module が Conversation であること。

  4. Events に conversation.created と conversation.visitor.replied の両方が含まれていること。

    注：「人工サービス - Other to Zoho Sales IQ」シナリオの Workflow でチェックするのは conversation.operator.replied / conversation.completed であり、訪問者のメッセージ送信ではトリガーされません。その Workflow が既に存在していても、インテグレーションシナリオが利用可能であるとは限りません。2 つのシナリオにはそれぞれ 1 本ずつの Workflow が必要です。

B. GPTBots 側：リクエストは受信したが破棄された

  1. URL のシナリオを取り違えている：インテグレーションシナリオは /api/console/bot/integration/chat/zoho/salesiq/{clientId}、人工サービスシナリオは /api/console/human/callback/zoho/salesiq/event です。逆に入力すると、対応する設定が見つからずメッセージが破棄されますが、Zoho 側では成功と表示され続けます。
  2. URL が別の環境を指している：ドメインが現在使用している環境と一致していることを確認してください。
  3. Secure your webhook を有効化したのに Public Key を入力していない：有効化すると Zoho は毎回のコールバックに署名を付与します。GPTBots 側の Public Key が空の場合、検証は必ず失敗し、リクエストは破棄されます。デバッグ段階では、まずこのオプションをオフにすることをおすすめします。
  4. エージェントが未公開：インテグレーションチャネルが読み取るのは公開済みバージョンです。エージェントが一度もバージョンを公開していない場合、メッセージは破棄されます。先にバージョンを保存して Publish をクリックしてください。
  5. 会話が他のオペレーターに引き受けられている：インテグレーションシナリオでは、会話がインテグレーション設定に入力した Email に対応する Zoho アカウントに帰属している必要があります。会話が他のオペレーターに手動で引き受けられた場合、訪問者のその後のメッセージはエージェントに転送されなくなります。
  6. 認可が失効している：GPTBots のインテグレーション設定ページに戻り、認可ステータスが正常であることを確認してください。同一の Client ID で認証が 20 件を超えると、最も早く認証されたエージェントが失効します（前述の注意を参照）。その場合は再認可が必要です。

3. Zoho 側ではメッセージを受信できるが、人工カスタマーサポートの返信が戻ってこない

これは典型的な「一方向通信」の現象で、原因は Webhook が有効になっていないことです。以下を確認してください。

  1. Settings - Workflows - Data Workflows に進み、該当の Workflow のステータスが ENABLED であることを確認します。
  2. Workflow で選択した Brands が実際に使用しているブランドと一致していることを確認します。
  3. Events に必要なイベントがチェックされており、URL に該当シナリオのアドレスが入力されていることを確認します（インテグレーションシナリオと人工サービスシナリオではアドレスが異なります。詳細は前述のステップ 8 の注意を参照してください）。
  4. リストの Last Triggered 列を確認します。常に空欄であったり、時刻が今回の会話と一致しない場合は、イベントが一度もトリガーされていないため、上記の設定を再確認してください。Failures 列は判断材料にできません（理由は前のよくある質問を参照）。

4. Secure your webhook を有効化した後、コールバックが失敗する

このオプションを有効化すると、Zoho は毎回のコールバックに署名を付与します。GPTBots 側に対応する Public Key が入力されていない場合、署名の検証に失敗し、そのリクエストは拒否されます。Zoho で In Use マークの付いた public key を GPTBots のインテグレーション設定ページにコピーしてください。デバッグ段階では、まずこのオプションをオフにして疎通を確認することもできます。