「APIコールを実行する」ステップでは、社内のCRMやERPなどの他のシステムへAPIコールを設定したり、Amazon Event BridgeやGoogleアナリティクスなどの外部のエンドポイントに会話の内容をプッシュすることが可能です。
この記事では、このステップを会話ボットに含めて設定する手順について説明します。
「APIコールを実行する」ステップとその設定ルールの概要については、「ボットのステップタイプについて：APIコールを実行する」を参照してください。
この記事では、次のセクションについて説明します。
「APIコールを実行する」ステップを追加する
「APIコールを実行する」ステップをボットに追加するには、いくつかの個別のタスクを行う必要があります。
「APIコールを実行する」ステップを追加するには
- 管理センターで、サイドバーにある「
チャネル」をクリックし、「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のパスまたはクエリの文字列値に変数を含めることができます。これにより、会話から外部システムにデータを渡すことができます。
たとえば、メッセージングボットは、「詳細を質問する」ステップを使用して、注文番号を入力するようカスタマーに求めることができます。その後、ボットは「APIコールを実行する」ステップを使用して、オンラインストアからその注文の出荷ステータスを取得することができます。
エンドポイントURLのドメインまたはサブドメイン内で変数を使用することはできません。次の表に、有効なエンドポイントURLの値と無効なエンドポイントURLの値の例を示します。
| 有効なエンドポイントURLの値 | 無効なエンドポイントURLの値 |
|---|---|
https://myshopify.com/admin/api/orders/order_number.jsonShopifyから注文IDを指定して注文を取得する。 
|
ドメイン/サブドメインに変数を追加することはできない |
|
Googleのplace APIからキーワード検索で場所を取得する |
クエリ文字列のキーに変数を追加することはできない |
変数が無効または空である場合、ボットは会話中にその変数をスキップします。
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コネクションの作成」を参照してください。
- 「APIコールを実行する」をクリックします。
- resultsの横にある「保存」をクリックします。
- 「値」ドロップダウンから、「Order」、「Image」の順に選択します。
デフォルトの変数名（image）を使用します。
- 「項目を追加」をクリックし、上記の手順を繰り返して、「Order Status」と「Item」の項目を作成します。
最大12個の項目（キーと値のペア）を追加できます。
- 「保存」をクリックします。
- ボットビルダーの「APIコールに成功」で「ステップを追加」をクリックし、「カルーセルを追加」を選択します。
- 「設定」パネルで、「動的メッセージに変換」をクリックします。
- 「配列」ドロップダウンで、「results」をクリックします。これは、上記で作成した配列です。
- タイトルでは、プラス記号（+）をクリックしresults.itemを選択します。
タイトルと説明には最大128文字まで入力できます。
- 「ボタンのリンク」で、プラス記号（+）をクリックし、results.imageを選択します。
- 「ボタンのテキスト」で、プラス記号（+）をクリックし、results.statusを選択します。
- 「画像のリンク」で、プラス記号（+）をクリックし、results.imageを選択します。
- 「完了」をクリックします。
動的カルーセルの例を以下に示します。
ステップの分岐について
「APIコールを実行する」ステップは、分岐ステップです。このステップを追加すると、APIが正常に実行されたかどうかによって、ボットの応答が分岐します。
- APIが応答コード400または500を返した。
- 保存された変数の1つが欠けているか、
null値があり、APIが応答コード200を返した。
それ以外の場合、ボットは成功の分岐をたどります。