メッセージング用AIエージェントでの「APIコールを実行」ステップの使用（旧バージョン）

Zendesk Documentation Team

編集日時：2025年5月15日

Suite

Team、Growth、Professional、EnterpriseまたはEnterprise Plus

この記事では、2025年2月2日時点でAIエージェントを試用または公開していたお客様のみが利用できる機能について説明します。AIエージェント - Advancedアドオンの同等の機能については、「その他のプラットフォームとAIエージェント - Advancedとの統合」を参照してください。

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

この記事では、このステップをメッセージング用AIエージェントに含めて設定する手順について説明します。

「APIコールを実行」ステップとその設定ルールの概要については、「AIエージェントのステップタイプについて：APIコールを実行」を参照してください。

この記事では、次のトピックについて説明します。

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

「APIコールを実行」ステップをAIエージェントに追加する

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

以下の手順は、すでにメッセージング用AIエージェントを作成してあり、そのAIエージェントにこのステップを追加することを想定しています。

メモ：呼び出されたシステムが10秒以内に応答しない場合、コールはタイムアウトになります。

「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の値

有効なエンドポイント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` クエリ文字列のキーに変数を追加することはできない

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

クエリ文字列のキーに変数を追加することはできない

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

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

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

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

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

「設定」パネルで「APIコールを実行」をクリックします。
アコーディオンを展開し、外部システムから変数に変換するデータを見付けます。

ヒント：「レスポンス本体」タブに切り替えると、外部システムから返された未加工応答が表示されます。
「保存」をクリックします。
新しい変数に名前を付けます。
変数名に使用できる文字は、小文字、数字、アンダースコアのみです。

APIコールで配列変数を渡す

「APIコールを実行」を使用して配列変数を渡し、外部システムにURLを提供することができます。外部システムにはAPIエンドポイントが必要です。APIエンドポイントとは、APIがリクエストを受け取り、レスポンスを送信するURLです。これで2つのシステムが相互にやりとりできるようになります。以下の例に示すように、レスポンスはJavaScript Object Notation（JSON）フォーマットでレンダリングされます。

{               
    "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",
	…

返されるデータを視覚化するために、配列変数の最初の項目のみが管理センターに表示されます。たとえば、上記のJSON出力では、id、name、address、item、price、imageがすべて表示されます。このデータは通常カルーセルに渡されますが、カルーセルはデータを最大10個までしか表示できません。

メモ：プロパティ値の最初の280文字だけがレスポンスに表示されます。

ネストされたJSON配列は、配列変数として保存することもできます。たとえば、以下のようなJSON出力がある場合、lastnameとfirstnameは別々の配列変数として保存できます。

"name": 
   {
      "lastname": "Cummings”,
      "firstname": “Alexander"
   },

配列や配列の値を管理センターのカルーセル設定内で編集することはできません。データを変更する必要がある場合は、管理センターで配列を削除し、新しい配列を作成する必要があります。

返された変数がNULLの場合、アイテムはカルーセルに表示されません。たとえば、次のようなシナリオで、変数{{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}}

例

この例では、注文の配列を返すAPIエンドポイントを使用して配列変数を作成します。注文の配列は、以下のようにAPIレスポンススニペットの"results"プロパティで指定します。


     {
  "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エージェントの応答が分岐します。

次のような場合、AIエージェントは失敗の分岐をたどります。

APIが応答コード400または500を返した。
保存された変数のいずれかが見つからないか、null 値である。

それ以外の場合、AIエージェントは成功の分岐をたどります。

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

69件のコメント

日付

新しい順

Alex Duffey

2025年2月07日

We need the character limit to be lifted. 280 is very small. Please look at opening this in the future. We are trying to a return an accessory list of products for one of our products, but the 280 limit stops us from providing that full list.
We tried breaking it up into multiple variables, but the the system requires us to save each one for each new product, which then runs into the 50 mac variable limit.
Please either raise the character limit to at least 1000 or raise the variable limit to at least 200.

Jeffrey Porter

2025年2月03日

Is it possible to include the originating URL for the page on which the chat bot was accessed in an API call? Our use case is that we are installing the chat bot on a video player and each video has a distinct URL. I created a chat bot flow that creates a Zendesk ticket. We'd like to be able to include the URL for the page in the ticket so we know where to go look for a problem. Right now we'd have to ask the user for something and we're guaranteed to get vague answers.

Aktie Projeto

2024年10月18日

Como faço para apagar variáveis que coloquei para teste e agora estão ocupando espaço no meu bot?

Yiannis Lamprou

2024年10月09日

I am trying to get data from hubspot via Make API call.
I am using POST method and i get all fields i want and can turn them to variable.

However the fields ( variables) are coming as numbers. (e.g "hs_pipeline_stage":"67655766",)

How can i say to ZD to display text according to the variable coming in?

Is there a way to create an array or so besides carousel?

{
"results":
[
{
"archived":false,
"createdAt":"2024-10-07T09:40:44.097Z",
"id":"3935559789",
"properties":
{
"content":"testtest",
"createdate":"2024-10-07T09:40:44.097Z",
"hs_lastmodifieddate":"2024-10-07T09:47:39.348Z",
"hs_object_id":"3937669789",
"hs_pipeline_stage":"67655766",
"hs_ticket_category":"TESTME",
"hs_ticket_id":"3937259789"},
"updatedAt":"2024-10-07T09:47:39.348Z"}
],
"total":1
}

이지훈

2024年9月11日

I have a similar question to 6336142945306
For example, I want to use users.json to allow end users to retrieve their information using an API.

If a user has a "custom_role_id" value, I can create a flow by saving that value as a variable.
However, if the flow is executed for a user who does not have a "custom_role_id" value, an API error is returned.

In conclusion, even null values should be saved as variables, and when the variable is referenced in the flow, a null value should be returned instead of an error.

Is this possible?

Nir Tzezana

2024年9月08日

Hi,
I have some data I want to add to the API request body, this is data that I already have when the chat window opened (no need to gather it from the user), how can I do that?

Fatima Sbeih

2024年8月19日

Has anyone managed to set this up with Stripe?

דורין אברבך

2024年5月12日

Hey, https://support.zendesk.com/hc/en-us/articles/4572971586586/comments/4614301298458 is there any updates?
about getting information from the user in order to use their input as parameters in API request

Javier DM

2024年4月29日

Hola muy buenas María!

Este caso que comentas, está justamente mencionado al pie de este artículo, donde pone:

Si la API devuelve un código de respuesta de 400, 500, o 200 con datos a los que les faltan cualquiera de las variables, el bot seguirá por la rama de fallas.

He visto este tipo de situaciones, cuando se quiere utilizar un null value como expresión boolean. Por eso la llamada puede ser exitosa (respuesta 200), pero el valor no corresponde a ninguna de las varlables que se han guardado para el flujo, por lo que el paso API fallará.

Un ejemplo:

En este caso, cuando el valor sea null el paso API va a fallar, por mas que la llamada sea exitosa. Ya que la variable aquí guardada es organization_id y null no es un valor exista para ese atributo.

Espero esta explicación te sea de utilidad. Si precisaras revisar tu caso en mas profundidad, te sugiero por favor dirigirte a support.zendesk.com/hc e iniciar una conversación con el bot para ponerte en contacto con nuestro equipo de soporte.

Saludos y que tengas buena semana!

María del Mar Beiras Neira

2024年4月26日

Buenas, he configurado la respuesta de Hacer una llamada a una API al revisar los Logs, veo que la respuesta fue “SUCCEEDED”, sin embargo entra por la rama de error de llamada API, entonces realmente no se que hacer para este caso, ya que no entiendo porque esta entrando por esa rama.

サインインしてコメントを残します。

アカウントの詳細情報

サインインして詳細を表示

サインインするとアカウントの詳細を一目で確認できます

サインイン

メッセージング用AIエージェントでの「APIコールを実行」ステップの使用（旧バージョン）

「APIコールを実行」ステップをAIエージェントに追加する

APIの詳細を追加する

APIコールで変数を渡す

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

APIコールで配列変数を渡す

ステップの分岐について

69件のコメント

アカウントの詳細情報

サインインして詳細を表示

その他のコンテンツ

よくあるトピック

ロールベースのガイド

その他のリソース

メッセージング用AIエージェントでの「APIコールを実行」ステップの使用（旧バージョン）

「APIコールを実行」ステップをAIエージェントに追加する

APIの詳細を追加する

APIコールで変数を渡す

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

APIコールで配列変数を渡す

ステップの分岐について

69件のコメント

アカウントの詳細情報

サインインして詳細を表示

その他のコンテンツ

関連記事