インテグレーションビルダーは、コーディング不要で使える強力なツールです。高度な技術やプログラミングの知識がなくても、AIエージェントをあらゆるAPIやデータソースに接続できます。これにより、チャットエクスペリエンスのパーソナライズや、動的コンテンツを活用した高度な自動解決が可能になります。
バックオフィスシステムから顧客情報にシームレスにアクセスでき、さらに外部のデータソースから情報を取得したり、サードパーティアプリと連携したりできる――そんなAIエージェントを、コードを一行も書かずに構築できるとしたらどうでしょうか。
動的コンテンツ機能により、インテグレーションビルダーではリアルタイムでのデータの取得・分析・変換が可能になります。これにより、AIエージェントは、個々のユーザーのニーズに応じた応答や推奨、解決策をカスタマイズして提供できるようになります。
インテグレーションビルダーは、ユーザーフレンドリーなインターフェイス、直感的な操作性、そしてコーディング不要の機能を備えたツールです。高度な技術的な知識がなくても、柔軟性とカスタマイズ性を最大限に活用できます。
この記事では、インテグレーションビルダーの主な機能と利点に加え、AIエージェントをさまざまなAPIやデータソースに接続する方法について、手順を追って解説します。
操作概要
インテグレーションビルダーにアクセスするには、サイドナビゲーションメニューの「APIインテグレーション」をクリックします。これにより、これ以降のインテグレーションはすべて概要リストにリストされるため、アクセスしやすくなります。最初は、オンボーディングの流れに応じて、APIインテグレーションがない状態で始まる場合と、サンプルのAPIインテグレーションが用意されている場合があります。
インテグレーションを新規作成する場合は、右上隅にある「インテグレーションを追加」をクリックします。
インテグレーションの名前を入力し、
追加のコンテキストを含む短い説明を追加します。
完了したら、「保存」をクリックしてインテグレーションの設定ページに進みます。
サイドナビゲーションにAPIインテグレーションが表示されない場合は、お客様がクライアント管理者ではないことを意味します。現在、インテグレーションビルダーへのアクセスはクライアント管理者に限定されています。この場合のアクセス権については、お客様の営業担当者にご相談ください。
動画や音声による説明をご希望の場合は、Zendeskのカスタムエンジニアリングチームのメンバー、クロエが制作した紹介ビデオをご覧ください。
リクエストパラメータ
まず初めに、APIから正しい応答を得るには、必要なリクエストパラメータを設定する必要があります。これらのリクエストパラメータには、会話中に取得した情報が含まれ、APIリクエストの仕様を定義する役割を果たします。たとえば、会話の中で特定のユーザー情報を取得・表示したい場合は、ユーザーIDをリクエストに含める必要があります。これにより、APIの応答に、チャット中のユーザーまたは訪問者に関連するデータが含まれるようになります。
以下は、設定されたリクエストパラメータの例です。
キーやリクエストパラメータの種類を指定するだけでなく、テスト値を設定することもできます。このテスト値は、画面右上のテスト機能を使用する際に参照されるため、あらかじめ設定しておくことお勧めします。オンラインチャット中は、リクエストを実行する前に、チャットのコンテキストに基づいた値がAPIインテグレーションに渡されます。しかし、テスト実行時には現在のチャットコンテキストが存在しないため、APIコールを正しく動作させるには、テスト値の設定が必要です。
「必須」チェックボックスを使うと、そのリクエストパラメータがオプションかどうか、またはセッションに保存されていない場合に、会話中に収集が必要かどうかを設定できます。
リクエストパラメータの追加方法は、呼び出すAPIの仕様によって異なります。リクエストパラメータをURLに追加するAPIもあれば、リクエストヘッダーやボディに追加するAPIもあります。リクエストパラメータをどこに追加すべきかについては、APIのドキュメントを参照してください。追加先が決まったら、二重波括弧で囲んだキー（{{userID}}）を使って、リクエストパラメータをURL、ヘッダー、またはボディに追加できます。
環境
リクエストパラメータを追加したら、「環境」セクションでAPIコールの主な設定を行います。ここでは、インテグレーションのテストや対話ビルダーで表示される環境名の横に、基本となるAPIドキュメントを参考にして、メソッド、URL、認証タイプを設定する必要があります。
認証タイプ
Zendeskでは以下の認証タイプを提供しています。
| 認証タイプ | 説明 | 例 |
| APIキー | APIオーナーが提供するシンプルなAPIキー。 |  |
| ベアラートークン | APIオーナーが提供するもうひとつのトークン。 |  |
| Basic認証 | ユーザー名とパスワードを使用してAPIに認証します。 |  |
| OAuth 2.0 | グラントタイプに応じて、いくつかの認証情報が必要とされます。 |  |
| カスタム | 有効期限トークンによる認証 | 詳しくは「インテグレーションビルダーでのカスタム認証の使用」を参照してください。 |
「認証なし」以外の認証タイプを使用する場合は、{{apiToken}} をヘッダーに追加して、リクエストに認証トークンを含める必要があります。具体的な記述例は、ヘッダーセクションにありますので、あわせてご確認ください。
ヘッダー
ヘッダーには、リクエストまたはクライアントとサーバー間の通信に関する追加情報が含まれます。これらは、リクエストのヘッダーセクションに含まれるキーと値のペアです。一般的に使用されるヘッダーには、以下のものがあります。
- Content-Type：リクエスト本文のデータのフォーマットを示します（例：JSON、XML、フォームデータ）。
- Authorization：リクエストを行うクライアントを認証するための認証情報またはトークンを提供します。
- User-Agent：リクエストを開始するユーザーエージェントを指定します。通常はWebブラウザまたはクライアントアプリケーションです。
- Accept：クライアントが受け入れるレスポンス形式をサーバーに通知します。
- Cache-Control：サーバーまたは中間キャッシュのキャッシュディレクティブ（指示）を定義します。
- X-Requested-With：クライアントが実行したリクエストのタイプ（XMLHttpRequest、Fetch APIなど）を識別します。
本文
APIリクエストの本文には、APIに送信されたデータが含まれます。これは通常、API側での処理やデータ操作に必要な入力データが必要なリクエストで使用されます。ボディには、呼び出すAPIや特定のエンドポイントに応じて、JSON、XML、プレーンテキスト、フォームデータなど、さまざまな形式のデータを含めることができます。現時点では、ZendeskでサポートしているのはJSONのみです。
環境の管理
ACEでは、APIのサンドボックス環境と本番環境の使い分けに関する課題に対応するため、インテグレーションビルダーに「環境」の概念を取り入れています。インテグレーションの設定時に自動的に作成されるデフォルトのメイン環境に加えて、追加の環境を柔軟に含めることができます。
これらの追加の環境により、URL、認証の詳細、ヘッダー、リクエストのボディをカスタマイズすることができ、API内の特定のサンドボックス環境または本番環境をターゲットにすることができます。
新しい環境を作成するには、環境セクションの横にある「＋」ボタンをクリックするだけです。既存の環境を複製するには、対象の環境にカーソルを合わせ、3点リーダー（…）メニューから「複製」を選択します。デフォルトとして設定できる環境は、1つだけです。デフォルト環境に設定されたものは、リストの最上部に表示され、DLBでは（変更しない限り）最初に自動的に選択されます。
AIエージェントによって使用されておらず、かつ、残り1つの環境でもデフォルトの環境でもない場合、その環境は削除できます。デフォルト設定を変更するには、3点リーダーメニューから該当するオプションを簡単に選択できます。
機能テスト
APIリクエストの設定が完了したら、すべての構成が正しく行われているかを確認しておくことをおすすめします。容易に確認できるよう、インテグレーションビルダーの右上隅に便利なテスト機能を装備しています。
テストボタンには「テスト」というラベルと、その後にデフォルト環境の名前が付けられているので、どの環境をテストするのか簡単に識別できます。このボタンをクリックすると、インテグレーションビルダーはリクエストパラメータと環境セクションから提供された情報を使用してAPIへのリクエストを開始します。APIから受信したレスポンスは、インターフェイスの右側にある「テストインテグレーション」セクションに表示されます。さまざまな環境からのリクエスト情報を使用してAPIをテストする場合は、テスト機能内のドロップダウンメニューから希望の環境を選択し、テストボタンを再度クリックします。
レスポンスの内容
「テストインテグレーション」セクション内では、APIから取得したレスポンスがインテグレーションビルダーに表示されます。レスポンスの内容は、以下のオブジェクトに整理されています。
| オブジェクト | コンテンツ | 例 |
| statusCode | HTTPレスポンスステータスコードは、特定のHTTPリクエストが正常に完了したかどうかを示します。詳しくはこちらを参照。 | "statusCode"：200 |
| data | データオブジェクトは、リクエストが成功した場合にAPIの関連データを示します。ただし、リクエストが成功しなかった場合は、対応するステータスコードに基づく追加情報を提供します。 |
"data": { "name":"Germany", "capital":"Berlin", "region":"Europe", "population":83240525, "area":357114 } |
| requestParameters | requestParametersオブジェクトには、インテグレーションビルダーがAPIを呼び出す際に使用したテスト値とともに、リクエストパラメータが表示されます。 |
"requestParameters": { "country": "de"} |
構成を変更した後は、テスト機能で再確認する前に、必ずインテグレーションを保存してください。
シナリオ
新しく作成されたインテグレーションには、あらかじめ3つのシナリオが設定されています。このうち2つのシナリオは、必要に応じてカスタマイズまたは削除が可能です。ただし、最後の「フォールバック」という名前のシナリオは編集できません。この「フォールバック」シナリオは、それまでのいずれのシナリオもトリガされなかった場合に、プライマリフォールバックとして機能します。
| シナリオ | デフォルトクエリ | 説明 |
| Success | statusCode >= 200 and statusCode < 300 | statusCode が 200～300 の間の値の場合に、優先パス/成功パスを捕捉するシナリオ。 |
| Failure | statusCode < 200 or statusCode >= 300 | statusCode が が 200～299 の範囲外の場合に備えた、失敗時の処理を行うシナリオ。 |
| Fallback | - | 常に少なくとも1つのシナリオをトリガするフォールバックシナリオ。 |
シナリオは、APIインテグレーションがトリガされた際に、会話が対話上でたどる複数の分岐（ブランチ）に相当します。
シナリオクエリ
各APIインテグレーションでは、1つのシナリオのみがトリガされます。会話中にどのシナリオがトリガされるかを決定するロジックは、シナリオクエリとシナリオの定義順序に基づいています。
シナリオクエリは、特定のシナリオをトリガするために必要な条件を定義します。インテグレーションビルダーは、その条件が満たされているかを判断するために、シナリオクエリとAPIレスポンス内のデータを照合・検証します。よく使用されるデータフィールドには、ステータスコード、APIレスポンスのデータオブジェクトに含まれる固有のデータ、リクエストパラメータの値などがあります。
成功シナリオのデフォルトのシナリオクエリでは、APIレスポンスのstatusCodeが 200～300 の範囲にある必要があります。この条件を満たすと、成功シナリオがトリガされます。
デフォルトのシナリオクエリは変更可能で、新しいシナリオを追加することもできます。そのため、APIレスポンスの内容によっては、複数のシナリオクエリが同時に条件を満たす場合もあります。このような場合、どのシナリオがトリガされるかは、シナリオの順序によって決まります。
現在のAPIレスポンスに基づいて、どのシナリオがトリガされるかを視覚的に確認できる機能が用意されています。この機能では、理論上は条件を満たしていても、より上位のシナリオが先にトリガされたために実行されなかったシナリオも識別されます。さらに、条件を満たしていないためにトリガされないシナリオは、別のスタイルでハイライト表示されます。
| 条件の結果 | 視覚表示 | 説明 |
| 最初に照合する条件 |  |
青い丸の付いたハイライト表示されたシナリオは、トリガされるシナリオを表します。 |
| 条件が一致しません |  |
白抜きの丸の付いたハイライト表示されたシナリオは、トリガされません。 |
| 最初の照合ではないが、条件が一致した |  |
灰色の丸が付いたシナリオは、理論上はトリガされます。 |
シナリオの順序を変更するには、対象のシナリオをクリックしてドラッグするだけです。フォールバックシナリオ（常に最後に配置される）を除けば、シナリオの順序は自由に調整できます。
セッションパラメータ
各シナリオの設定時には、バックエンドシステムから取得したさまざまなデータポイントを使って、会話を拡張できます。APIレスポンスから得られた関連情報を変換し、セッションパラメータとして保存することで、各シナリオから必要なデータにアクセスできるようになります。保存されたセッションパラメータは、対話構築のプロセスで、訪問者に情報を提示したり、基本的なワークフローを設計したりするために活用できます。
セッションパラメータはキーと値のペアで定義されます。キーはダイアログビルダー内で参照として使用されますが、クエリはAPIレスポンスから特定のデータを変換し、抽出して値を保存するために使用されます。インテグレーションビルダーでは、現在のレスポンスに基づいて、保存された値がレスポンス値フィールドにどのように表示されるかをリアルタイムで確認できます。
上の画像では、セッションパラメータキーが「capital」として定義されており、DLB内では二重波括弧 {{capital}} を使用して参照することができます。クエリは、どのデータをセッションパラメータの値として変換し保存するかを決定します。この場合、APIレスポンスのデータオブジェクト内の「capital」フィールドからコンテンツを抽出します。
クエリ言語 - JSONata
JSONataは、シナリオレベルとセッションパラメータレベルの両方で使用できるクエリ言語です。「シンプルなクエリは簡単に書ける」という原則のもとに設計されており、技術に詳しい方だけでなく、そうでない方にも扱いやすくなっています。習得が容易で、すぐに使いこなせるのも特長です。JSONataを使えば、基本的な処理のほか、日付の変換や、複数のデータポイントの統合なども可能です。
JSONataは、クエリと言語変換の両方に対応した言語であり、公式ドキュメントが公開されています。詳しくはこちらのリンクからご覧いただけます。