フロービルダーでの「APIコールを実行する」ステップの使用

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

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

「APIコールを実行する」ステップとその設定ルールの概要については、「ボットフローのステップタイプについて：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://プロトコルをサポートしています。
4. オプションで、APIコールを認証するためのコネクションを選択します。
   メモ：APIコールの認証の前に、コネクションを作成する必要があります。
5. 必要であれば、オプションのヘッダーのキーと値を入力します。
6. 「APIコールを実行する」ボタンをクリックし、テストコールを行います。ステップのURLやヘッダーに変数が追加されている場合、外部サービスにオプションのテストデータを入れて、APIコールが期待通りに動作しているかどうかを確認することができます。設定されたエンドポイントURLに対してHTTPリクエストが行われることに注意してください。

APIレスポンスを変数として保存する

変数はAPIレスポンスを保存する方法です。変数はいくつかの異なる方法で使用できます。

• ボットがお客様に伝えるメッセージをパーソナライズする。たとえば、カスタマーの名前を変数として保存し、ボットメッセージでそれを参照することができます。変数が作成された「APIコールを実行する」ステップの後、設定可能なメッセージが含まれる以下のステップでは、フローのどこにでも変数を追加することができます。
  • メッセージの送信
  • オプションの提示
  • ヘルプセンター記事の表示
  • エージェントへの転送

• APIコールのデータを外部システムに渡す。たとえば、カスタマーに注文番号の入力を促し、その注文の出荷状況についてeコマースシステムにAPIコールを実行することができます。「APIコールを実行する」ステップで変数を使用する場合、注意すべきいくつかの制約があります。

  「エンドポイント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コールを実行する」ステップでは、最大8つの変数を作成できます。

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

「APIの詳細」を設定してAPIコールをテストしたら、返されたレスポンスデータを使用して変数を作成できます。以下の手順は、前のセクションの手順の続きです。

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

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

APIコールを認証する

APIコールを実行するステップでは、コネクションを使用して、外部サービスまたはシステムに対するAPIコールを認証することができます。

これを行うには、まず管理センターでコネクションを作成する必要があります。コネクションを使用すると、サービスの資格情報を安全に保存および渡すことができます。コネクション作成の手順について詳しくは、「管理センターでのコネクションの作成」を参照してください。

コネクションの追加に問題がある場合は、管理センターの監査ログの情報を確認してください。

ステップの分岐について

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

ボット実行時に、200のレスポンスコードがあると、ボットは、成功した場合の分岐に進みます。400または500のレスポンスコードでは、ボットは失敗した場合の分岐に進みます。APIが空のレスポンスで200を返した場合、このステップで保存された変数は、実行時にスキップされることに注意してください。

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