この記事では、このステップをメッセージング用AIエージェントに含めて設定する手順について説明します。
「APIコールを実行」ステップとその設定ルールの概要については、「AIエージェントのステップタイプについて：APIコールを実行」を参照してください。
この記事では、次のトピックについて説明します。
「APIコールを実行」ステップをAIエージェントに追加する
「APIコールを実行」ステップをAIエージェントに追加するには、いくつかの個別のタスクを行う必要があります。
「APIコールを実行」ステップを追加するには
- 管理センターで、サイドバーの「
AI」をクリックし、「AIエージェント」>「AIエージェント」を選択します。 - 「メッセージング用のAIエージェントの管理」をクリックします。
- 編集するAIエージェントの名前をクリックします。
- 「回答」タブをクリックし、新しい回答を作成するか、既存の回答を開きます。
- ボットビルダーで、ステップを挿入したい場所（分岐の最後、または既存の2つのステップの間）で、「ステップを追加」アイコンをクリックします。
- 「設定」パネルで「APIコールを実行」をクリックします。
- ステップの説明を入力します。
- 名前：チームが識別しやすいコールの名前。
- 説明（オプション）：コールが実行するアクションの簡単な説明。
この情報はカスタマーには表示されません。
- 「APIの詳細を追加する」のセクションの手順に進みます。
APIの詳細を追加する
APIの詳細セクションを使用して、HTTPリクエストメソッド、外部リソースの場所、および必要に応じてヘッダーの追加など、実行するHTTPコールを設定します。以下の手順は、前のセクションの手順の続きです。
APIの詳細を追加するには
- 「設定」パネルで、「APIの詳細」をクリックします。
- 「リクエスト方法」を以下から選択します。
- GET：APIサービスから外部リソースを取得します。これは、最もよく使用される方法です。
- POST：外部システムでリソースを作成するためのデータを送信します。リソースがすでに存在する場合は、送信されたデータによってリソースが変更されます。
- PUT：リソースを更新するためのデータを送信します。
- PATCH：外部サイトのリソースを更新するためのデータを送信します。リソースの部分的な変更を適用するために使用されます。
- DELETE：外部サイトのリソースを削除します。
-
エンドポイントURLを入力します。
エンドポイントURLは、接続先の外部リソースの場所です。エンドポイントURLは、
https://プロトコルをサポートしています。URLのパスやクエリ文字列の値に変数を含めることができます。詳細については、「APIコールで変数を渡す」を参照してください。 - オプションで、APIコールを認証するためのコネクションを選択します。
メモ：コネクションを「APIコールを実行」ステップで使用する前に、コネクションを作成する必要があります。
- 必要であれば、オプションのヘッダーのキーと値を入力します。重要：認証にヘッダーを使用しないでください。今後はAPIコネクションを使用してください。
認証関連のヘッダー（
authorizationやx-api-keyなど）を含む「APIコールを実行」ステップは自動的に失敗します。「APIコールを実行」ステップが失敗すると、会話はそのステップの「APIコールに失敗」分岐に移動します。 - 「APIコールを実行」をクリックして、APIコールをテストします。
ステップのURLやヘッダーに変数が追加されている場合、外部サービスにオプションのテストデータを入れて、APIコールが期待通りに動作しているかどうかを確認することができます。設定されたエンドポイントURLに対してHTTPリクエストが行われることに注意してください。
APIコールで変数を渡す
APIコールのエンドポイントURLを入力する際に、URLのパスまたはクエリの文字列値に変数を含めることができます。これにより、会話から外部システムにデータを渡すことができます。
たとえば、メッセージング用AIエージェントは、「詳細を質問」ステップを使用して、注文番号を入力するようカスタマーに求めることができます。その後、AIエージェントは「APIコールを実行」ステップを使用して、オンラインストアからその注文の出荷ステータスを取得することができます。
エンドポイントURLのドメインまたはサブドメイン内で変数を使用することはできません。次の表に、有効なエンドポイントURLの値と無効なエンドポイントURLの値の例を示します。
| 有効なエンドポイントURLの値 | 無効なエンドポイントURLの値 |
|---|---|
https://myshopify.com/admin/api/orders/order_number.jsonShopifyから注文IDを指定して注文を取得する。 
|
ドメイン/サブドメインに変数を追加することはできない |
|
Googleのplace APIからキーワード検索で場所を取得する |
クエリ文字列のキーに変数を追加することはできない |
変数が無効または空である場合、AIエージェントは会話中にその変数をスキップします。
APIレスポンスの変数を保存する
APIコールの詳細を設定し、テストした後、APIコールのJSONレスポンスの値を変数として保存することができます。「APIコールを実行」ステップでは、最大12つの変数を保存できます。変数の値の最初の280文字のみが保存されます。
レスポンスデータから変数を作成するには
- 「設定」パネルで「APIコールを実行」をクリックします。
- アコーディオンを展開し、外部システムから変数に変換するデータを見付けます。
ヒント：「レスポンス本体」タブに切り替えると、外部システムから返された未加工応答が表示されます。
- 「保存」をクリックします。
- 新しい変数に名前を付けます。
変数名に使用できる文字は、小文字、数字、アンダースコアのみです。
APIコールで配列変数を渡す
{
"info": {
"count": 50,
"pages": 2,
"next": "https://mycompany.com/api/orders?page=2",
"prev": null
},
"results": [
{
"id": 1052,
"name": "Alexander Cummings",
“address”: “123 MyStreet”,
"Item": "belt",
"price": "15.00",
"image": "https://mycompany.com/api/orders/avatar/1.jpeg",
…
id、name、address、item、price、imageがすべて表示されます。このデータは通常カルーセルに渡されますが、カルーセルはデータを最大10個までしか表示できません。
lastnameとfirstnameは別々の配列変数として保存できます。
"name":
{
"lastname": "Cummings”,
"firstname": “Alexander"
},
配列や配列の値を管理センターのカルーセル設定内で編集することはできません。データを変更する必要がある場合は、管理センターで配列を削除し、新しい配列を作成する必要があります。
{{customer.order}}の値が空であるとします。カード1の場合、カードには「Order number」というタイトルの一部がレンダリングされます。カード2の場合、結果のタイトルは空なので、カード2はレンダリングされません。
Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}
Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}
例
{
"info": {
"count": 5,
"pages": 1
},
"results": [
{
"createdAt": "July 10, 2023",
"name": "Connie Stokes",
"Shippingaddress": "123 Street, City, State",
"order": {
"Status": "Ordered",
"Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
},
"Quantity": 1,
"Price": 45,
"Item": "Shirt",
"id": "1"
},
… この例を使って、「APIコールを実行」ステップを使って配列変数を作成し、動的カルーセルを使用してエンドユーザーに結果を表示します。
配列を作成するには
- 「設定」パネルで「APIコールを実行」をクリックします。
- 名前に「orders」と入力します。
- 「設定」パネルで、「APIの詳細」をクリックします。
- 「リクエスト方法」ドロップダウンをクリックし、「GET」を選択します。
- エンドポイントURLのURLを入力します。
- 「認証」で、認証方法を選択します。
詳細については、「外部サービスと統合するためのコネクションの作成」を参照してください。
- 「APIコールを実行」をクリックします。
- resultsの横にある「保存」をクリックします。
- 「値」ドロップダウンから、「Order」、「Image」の順に選択します。
デフォルトの変数名（image）を使用します。
- 「項目を追加」をクリックし、上記の手順を繰り返して、「Order Status」と「Item」の項目を作成します。
最大12個の項目（キーと値のペア）を追加できます。
- 「保存」をクリックします。
- ボットビルダーの「APIコールに成功」で「ステップを追加」をクリックし、「カルーセルを追加」を選択します。
- 「設定」パネルで、「動的メッセージに変換」をクリックします。
- 「配列」ドロップダウンで、「results」をクリックします。これは、上記で作成した配列です。
- タイトルでは、プラス記号（+）をクリックしresults.itemを選択します。
タイトルと説明には最大128文字まで入力できます。
- 「ボタンのリンク」で、プラス記号（+）をクリックし、results.imageを選択します。
- 「ボタンのテキスト」で、プラス記号（+）をクリックし、results.statusを選択します。
- 「画像のリンク」で、プラス記号（+）をクリックし、results.imageを選択します。
- 「完了」をクリックします。
動的カルーセルの例を以下に示します。
ステップの分岐について
「APIコールを実行」ステップは、分岐ステップです。このステップを追加すると、APIリクエストが正常に実行されたかどうかによって、AIエージェントの応答が分岐します。
- APIが応答コード400または500を返した。
- 保存された変数のいずれかが見つからないか、
null値である。
それ以外の場合、AIエージェントは成功の分岐をたどります。