現在のプランを確認
アドオン AIエージェント - Advanced

インテグレーションビルダーでは、リクエストパラメータを使用して、AIエージェントの会話からデータ（会話パラメータ）を取得し、外部のエンドポイントに渡すことができます。場合によっては、APIリクエストでURLクエリまたはリクエストボディとして送信する前に、このデータを変換または再フォーマットする必要があります。そのために、強力なクエリおよび変換言語のJSONataを使用できます。

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

  • リクエストパラメータ値を再フォーマットする
  • 値を再フォーマットする一般的なユースケースの例

関連記事：

  • インテグレーションビルダーのリソース

リクエストパラメータ値を再フォーマットする

JSONataを使用して、リクエストパラメータ値を再フォーマットできます。

リクエストパラメータ値を再フォーマットする手順

  1. AIエージェント（Advanced）の右上のAIエージェントドロップダウンフィールドを使用して、AIエージェントを選択します。
  2. 左側のメインメニューで、APIインテグレーションをクリックします。
  3. インテグレーションを選択または作成します。
  4. リクエストパラメータページで、値を再フォーマットするリクエストパラメータを選択または作成します。
  5. 値をテストフィールドで、値の再フォーマットアイコン（）を選択します。
  6. 値の再フォーマットダイアログのJSONata再フォーマットフィールドで、JSONataを使用して、選択したリクエストパラメータキーに関連付けられた値を変換または再フォーマットします。
    JSONataクエリで「$」を使用して、再フォーマットする値のキーを表示します。
    テスト値プレビューフィールドでは、クエリの結果をリアルタイムで確認できます。
  7. 「完了」をクリックします。
  8. （オプション）APIリクエストのボディにリクエストパラメータを追加する場合：
    1. 左側の環境ヘッダーで、適切な環境を選択します。
    2. ボディタブを選択します。
    3. リクエストパラメータを二重の中括弧で囲んだ値として使用し、JSONオブジェクトを追加します。

値を再フォーマットする一般的なユースケース

インテグレーションビルダーでは、特定のキーに割り当ててリクエストパラメータを定義できます。これらの値はそのままでも機能しますが、シナリオによっては、外部システムの要件に合わせて変換または再フォーマットする必要があります。

たとえば、以下のような操作ができるようになります。

  • 日付の再フォーマット：API要件に合わせて、日付の形式をMM/DD/YYYYからYYY-MM-DDまたはISO 8601に変更します。
  • 文字列操作の実行：文字列の操作（文字の追加や削除、複数のフィールドの結合、HTMLを含む文字列への変換など）
  • 条件付きロジックの適用：フィールドが空かどうかのチェックや、必要に応じて、デフォルト値の割り当てなどの条件を適用します。

ここでは、次の例について説明します。

  • シナリオ：日付を再フォーマットする
  • シナリオ：URLを再フォーマットしてクリック可能なリンクに変換する
  • シナリオ：チャットの会話ログを再フォーマットして可読性を高める

シナリオ：日付を再フォーマットする

このシナリオでは、エンドポイントの日付形式がYYYY-MM-DD形式またはISO 8601形式であるか確認する必要があります。ただし、会話の場合、日付はユーザーにわかりやすいDD/MM/YYYY形式にします。

このシナリオで使用するJSONataクエリを以下に示します。

$substring($, 6, 10) & "-" & $substring($, 3, 2) & "-" & $substring($, 0, 2)

シナリオ：URLを再フォーマットしてクリック可能なリンクに変換する

このシナリオでは、http://またはhttps://で始まり、空白以外の文字が続くテキスト（部分文字列）を検索して、URLをクリック可能なリンクに変換します。次に、JSONataの$replace関数を使用して、その部分文字列を、一致したURLをHTMLの<a>タグでラップした文字列に置き換え、クリック可能なリンクを作成します。

このシナリオで使用するJSONataクエリを以下に示します。

(
$text := "Chat transcript unavailable. Here is a link:https://www.zendesk.com. Here is another link: https://www.w3schools.com.";

$replace($text, /(https?:\/\/[^\s]+)/, '<a href="$1">$1</a>'
)

シナリオ：チャットの会話ログを再フォーマットして可読性を高める

このシナリオでは、チャットの会話ログをチケットに追加します。ただし、デフォルトのフォームでは、チャットの会話ログは読みやすくありません。

  • チャットの会話ログ - 2024-10-12（13:04:10）AIエージェント：カスタマーエンジニアリングAIエージェントへようこそ。（13:04:10）AIエージェント：テスト対象のインテグレーションを選択：（13:04:10）訪問者：test c.id: d501304d-da09-4485-a4c7-1c708ec0005d（UTC時間）

各メッセージを行に分割して、ユーザーにわかりやすい形式に変換します。JSONataを使用して、開き括弧「（」を「改行+「（」」に置き換えて、メッセージの各行が開き括弧「（」で始まるようにします。

再フォーマットされた会話は次のようになります。

  • チャットの会話ログ - 2024-10-12
    （13:04:10）AIエージェント：インテグレーションビルダーAIエージェントへようこそ。
    （13:04:10）AIエージェント：テスト対象のインテグレーションを選択：
    （13:04:10）訪問者：test c.id: d501304d-da09-4485-a4c7-1c708ec0005d（UTC時間）

このシナリオで使用するJSONataクエリを以下に示します。

$replace($, “(“, “\n(“)

さらに、リクエストと共に送信されるように、このパラメータを環境のボディセクションに追加する必要があります。

{
"chatTranscript": "{{chatTranscript}}"
}

Powered by Zendesk