会話ボットでの「APIコールを実行する」ステップの使用

注意：ボット関連の機能について名称が変更されました。今後は、Answer Botは「Zendeskボット」、フロービルダーは「ボットビルダー」、推奨記事の提示は「オートリプライ」になります。一部の古い機能では、古い用語がまだ使用されており、それらに関するドキュメントでは古い用語が引き続き使われています。この名称変更の詳細については、こちらの製品関連の告知をお読みください。

「APIコールを実行する」ステップでは、社内のCRMやERPなどの他のシステムへAPIコールを設定したり、Amazon Event BridgeやGoogleアナリティクスなどの外部のエンドポイントに会話の内容をプッシュすることが可能です。

この記事では、このステップを会話ボットに含めて設定する手順について説明します。

「APIコールを実行する」ステップとその設定ルールの概要については、「ボットフローのステップタイプについて：APIコールを実行する」を参照してください。

この記事では、次のセクションについて説明します。

• 「APIコールを実行する」ステップを追加する
• APIの詳細を追加する
• APIレスポンスの変数を保存する
• ステップの分岐について

「APIコールを実行する」ステップを追加する

「APIコールを実行する」ステップをボットに追加するには、いくつかの個別のタスクを行う必要があります。

以下の手順は、すでに会話ボットを作成してあり、そのボットにこのステップを追加することを想定しています。

「APIコールを実行する」ステップを追加するには

1. ボットビルダーでボットを開きます。
2. ステップを挿入したい場所（分岐の最後、または既存の2つのステップの間）で、「新規作成」アイコンをクリックします。
3. 「設定」パネルで「APIコールを実行する」をクリックします。
4. ステップの説明を入力します。入力した情報はチームメンバーにのみ表示され、カスタマーには表示されません。
   • 名前：チームが識別しやすいコールの名前。
   • 説明（オプション）：コールが実行するアクションの簡単な説明。
5. 次の「APIの詳細を追加する」のセクションの手順に進みます。

APIの詳細を追加する

APIの詳細セクションを使用して、HTTPリクエストメソッド、外部リソースの場所、および必要に応じてヘッダーの追加など、実行するHTTPコールを設定します。以下の手順は、前のセクションの手順の続きです。

APIの詳細を追加するには

1. 「設定」パネルで、「APIの詳細」をクリックします。
2. ドロップダウンから、以下のHTTPリクエストメソッドを選択します。
   • GET：外部リソースのサーバーからデータを取得します。これは、最もよく使用される方法です。
   • POST：外部システムのリソースを作成または更新するためのデータを送信します。リソースがすでに存在する場合は、送信されたデータによってリソースが変更されます。
   • PUT：リソースを更新または作成するためのデータを送信します。リソースが既に存在する場合は、送信されたデータによってリソースが置き換えられます。
   • PATCH：外部サイトのリソースを更新するためのデータを送信します。リソースの部分的な変更を適用するために使用されます。
   • DELETE：外部サイトのリソースを削除します。
3. エンドポイントURLを入力します。エンドポイントURLは、接続先の外部リソースの場所です。エンドポイントURLは、https://プロトコルをサポートしています。URLのパスやクエリ文字列の値に変数を含めることができます。詳細については、「APIコールで変数を渡す」を参照してください。
4. オプションで、APIコールを認証するためのコネクションを選択します。
   メモ：コネクションを「APIコールを実行する」ステップで使用する前に、コネクションを作成する必要があります。
5. 必要であれば、オプションのヘッダーのキーと値を入力します。
   重要：認証にヘッダーを使用しないでください。今後はAPIコネクションを使用してください。

   認証関連のヘッダー（authorizationやx-api-keyなど）を含む「APIコールを実行する」ステップは自動的に失敗します。「APIコールを実行する」ステップが失敗すると、会話はそのステップの「APIコールに失敗」分岐に移動します。

6. 「APIコールを実行する」をクリックして、APIコールをテストします。ステップのURLやヘッダーに変数が追加されている場合、外部サービスにオプションのテストデータを入れて、APIコールが期待通りに動作しているかどうかを確認することができます。設定されたエンドポイントURLに対してHTTPリクエストが行われることに注意してください。

APIコールで変数を渡す

APIコールのエンドポイントURLを入力する際に、URLのパスまたはクエリの文字列値に変数を含めることができます。これにより、会話から外部システムにデータを渡すことができます。

たとえば、メッセージングボットは、「詳細を質問する」ステップを使用して、注文番号を入力するようカスタマーに求めることができます。その後、ボットは「APIコールを実行する」ステップを使用して、オンラインストアからその注文の出荷ステータスを取得することができます。

エンドポイントURLのドメインまたはサブドメイン内で変数を使用することはできません。次の表に、有効なエンドポイントURLの値と無効なエンドポイントURLの値の例を示します。

有効なエンドポイントURLの値	無効なエンドポイントURLの値
https://myshopify.com/admin/api/orders/order_number.json Shopifyから注文IDを指定して注文を取得する。	https://domain.com/api/search?input=value ドメイン/サブドメインに変数を追加することはできない
https://maps.googleapis.com/maps/api/place?input=city_name Googleのplace APIからキーワード検索で場所を取得する	https://example.com/api/search?key=value クエリ文字列のキーに変数を追加することはできない

変数が無効または空である場合、ボットは会話中にその変数をスキップします。

メモ：変数の値は自動翻訳されません。メッセージングの会話で自動翻訳を使用する場合は、この点に留意してください。

APIレスポンスの変数を保存する

APIコールの詳細を設定し、テストした後、APIコールのJSONレスポンスの値を変数として保存することができます。「APIコールを実行する」ステップでは、最大8つの変数を保存できます。

メモ：メッセージング会話で表示される応答には、変数の値の最初の280文字のみが表示されます。

レスポンスデータから変数を作成するには

1. 「設定」パネルで「APIコールを実行する」をクリックします。
2. アコーディオンを展開し、外部システムから変数に変換するデータを見付けます。
   ヒント：「レスポンス本体」タブに切り替えると、外部システムから返された未加工応答が表示されます。
3. 「保存」をクリックします。
4. 新しい変数に名前を付けます。変数名に使用できる文字は、小文字、数字、アンダースコアのみです。

ステップの分岐について

「APIコールを実行する」ステップは、分岐ステップです。このステップを追加すると、APIが正常に実行されたかどうかによって、ボットの応答が分岐します。

APIが応答コード400、500、200のいずれかを返し、そのデータがいずれかの変数に欠けている場合、ボットはエラーのブランチの下に移動します。

注意：「APIコールを実行する」ステップを使用する場合、接続する外部システムが「Zendesk以外の第三者サービス」（「メインサービス契約」に定義）であることを了承するものとします。Zendeskは、ボットビルダーの拡張機能の使用によって可能になる「Zendesk以外の第三者サービス」については運営も管理も行いません。また、Zendeskはお客様または「Zendesk以外の第三者サービス」の法的または規制遵守義務について責任を負いません。