クライアント側またはサーバー側のAPIを使用して会話イベントを送信する

最終更新日: 2026年06月17日 08:27

Pendo Conversations APIを使用すると、フロントエンドまたはバックエンドのコードから、訪問者が送信したプロンプト、エージェントの応答、訪問者からのフィードバックなど、AIエージェントとのやり取りの全内容を記録することができます。このデータは、ユースケースの特定、問題の検出、会話のレビューなどのエージェントアナリティクス機能を支えます。

この記事では、クライアント側とサーバー側の実装方法について説明します。エージェントアナリティクスデータの送信方法については、「Pendoにエージェントアナリティクスデータを送信する」を参照してください。

要件

クライアント側またはサーバー側の方法で会話イベントを送信するには、以下が必要です。

Pendoでエージェントに対して全会話が有効化されていること。設定手順については、「PendoでのAIエージェントの追加と設定」を参照してください。
計測対象とするエージェントのエージェントID。これを確認するには、［プロダクト］>［エージェントアナリティクス］の順に選択し、エージェント名の横にある設定アイコンを選択してください。
プロダクトのコードベースへのアクセスと、変更をデプロイできる開発者環境。
サーバー側のメソッドを使用している場合、アプリケーション用のトラッキングイベント共有シークレット。取得手順については、以下の「サーバー側での会話イベントの送信」を参照してください。

クライアントサイドで会話イベントを送信する

アプリのフロントエンドコードを更新して、AIエージェントがユーザー操作を処理する箇所すべてでwindow.pendo.trackAgent()を呼び出すようにしてください。この方法はプロンプト、回答、訪問者からのフィードバックを収集します。

AIエージェントのUIと同じランタイムコンテキストで、window.pendoが利用可能であることを確認してください。たとえば、Pendo Web SDKの初期化が完了した後などです。

構文

window.pendo.trackAgent(eventType, agenticProperties, properties)

パラメータ

eventType（文字列、必須）："prompt"、"agent_response"、"user_reaction"のいずれか。
agenticProperties（オブジェクト、必須）：イベント固有の会話データおよびメタデータ。サポートされているフィールドの一覧については、「会話のプロパティ」を参照してください。
properties（オブジェクト、任意）：durationやexperimentなどの標準的なPendoのイベントプロパティ。これらは会話プロパティと一緒に送信され、イベントペイロードにeventPropertiesオブジェクトとして表示されます。

会話の流れの例

以下の例は、訪問者へのプロンプトの送信、エージェントの応答の記録、訪問者からのフィードバックの取得を、同じ会話の中で行う方法を示しています。

重要 : タイムスタンプとIDによってメッセージの順序が維持されることを確認してください。誤ったシーケンスはセッション分析に影響を与える可能性があります。

会話内の各メッセージには一意のmessageIdが必要です。プロンプトとエージェントの応答は別々のメッセージであり、異なるIDを使う必要があります。フィードバックは、それに関連付けられた応答のmessageIdを再利用します。

訪問者が以下のプロンプトを送信します。

window.pendo.trackAgent('prompt', {
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_prompt_001',
  content: 'How do I reset my password?',
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: [],
  agentFilesUploaded: []
});

エージェントが応答します。

window.pendo.trackAgent('agent_response', 
{
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_response_001',
  content: 'To reset your password, go to Settings > Account > Reset Password.',
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: ['knowledge_base'],
  agentFilesUploaded: []
},
{
  experiment: 'experiment_abc'
});

訪問者がエージェントの回答に反応：

window.pendo.trackAgent('user_reaction', {
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_response_001', // Reuses the response ID to tie feedback to it
  content: 'positive', // 'positive', 'negative', or 'unreact'
  agentUserReactionComments: ['that feedback was really useful!'],
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: ['knowledge_base'],
  agentFilesUploaded: []
});

その他の例

訪問者はプロンプトとともにファイルをアップロードします。

window.pendo.trackAgent('prompt', {
  agentId: 'document-analyzer123',
  conversationId: 'conv_456',
  messageId: 'msg_789',
  content: 'Analyze this spreadsheet for trends',
  agentModelsUsed: ['gpt-4'],
  suggestedPrompt: false,
  agentFilesUploaded: [{ "type": "csv", "name": "data.csv" }]
});

訪問者は提案されたプロンプトを使用します。

window.pendo.trackAgent('prompt', {
  agentId: 'writing-assistant123',
  conversationId: 'conv_321',
  messageId: 'msg_654',
  content: 'Write a professional email to a client',
  agentModelsUsed: ['claude-3'],
  suggestedPrompt: true,
  agentFilesUploaded: []
});

サーバーサイドで会話イベントを送信する

お使いの環境でPendo Web SDKが利用できない場合（たとえば、モバイルアプリ、バックエンドサービス、またはWeb以外の環境など）は、サーバー側のメソッド方式を使用してください。

サーバー側のリクエストを認証するには、アプリケーション用のトラックイベント共有シークレットが必要です。これは、Pendoのインストール情報やインテグレーションキーに記載されているサブスクリプションキーとは異なります。

サブスクリプション管理者は、［設定］>［サブスクリプション設定］>［アプリケーション］に移動し、関連するアプリを選択してから、［トラックイベントの共有秘密（Track Event shared secret）］の横にある［表示（Show）］を選択することで、共有秘密鍵にアクセスできます。

共有シークレットを取得したら、Conversations APIエンドポイントのドキュメントを参照して、リクエストのフォーマットに関する技術的な詳細（地域別エンドポイント、必須ヘッダー、コード例など）を確認してください。

サーバー側のリクエスト本文は、クライアント側のメソッドと同じプロパティスキーマを使用します。プロパティの定義については、「会話プロパティ」を参照してください。

処理と可視性

会話データは1時間ごとにバッチ処理されます。コードが本番環境で稼働した後、通常、次のバッチ処理が開始されてから15分以内に新しいメッセージが表示されます。［プロダクト］>［エージェントアナリティクス］の会話データを確認するには、エージェントを選択し、［会話］タブを開きます。

サーバーサイドの会話イベントは、トラックイベントと同じタイムスタンプ処理ルールに従います。可能な限り現在のタイムスタンプを使用してください。現在の時間外の過去のタイムスタンプを持つイベントは、毎日または毎週の再処理が行われるまで表示されません。Pendoは7日以上前のタイムスタンプを持つイベントを処理できません。

サーバサイドエージェントイベントを通じてのみ対話する訪問者は、エージェントアナリティクスに表示されますが、［訪問者］ページに反映されず、アプリケーションのアクティブ時間としてカウントされません。［トラックイベントをアプリ滞在時間としてカウント］設定は、エージェントイベントには適用されません。

ヒント：アプリケーションでAPI呼び出しの再試行やイベントの再生を行う場合は、Pendoでのレコードの重複を防ぐため、同じmessageIdを再利用してください。