AI Feedback API

リクエスト要件と制限

すべてのエンドポイントはHTTP Basic認証を使用します。プロジェクトのAPIキーをユーザー名として使用し、シークレットキーをパスワードとして使用してください。
リクエスト本文はContent-Type: application/jsonを含むJSON形式でなければなりません。
最大ペイロードサイズは5MBです。
各リクエストにつき、1～100個のフィードバックアイテムに対応します。
Amplitudeは、ソース内のunique_idを使用して、アイテムや会話パートの重複排除を行います。Amplitudeは既存のレコードをアップサート（更新・挿入）するため、同じデータを2回送信しても安全です。
既存のアイテムに新しい会話パートを追加するには、同じunique_idでアイテムを再送信し、新しいパートを含めます。Amplitudeによって既存のパート（unique_idと一致するもの）がアップサートされ、新しいパートが追加されます。

ソースIDの検索

Webhookソースのsource_idを見つけるには、AI Feedbackのソース詳細ページに移動し、3つのドットメニューを選択してから、[設定]を選択します。このページには、ソースIDと要求例が表示されます。

EU域内のデータレジデンシー

EU域内にデータが保存されている場合、ベースURLにはhttps://amplitude.comではなくhttps://eu.amplitude.comを使用します。例えば：

フィードバックの取り込み：POST https://eu.amplitude.com/api/1/ai-feedback/ingest。

フィードバックの取り込み

カスタマーからのフィードバックアイテムをAmplitudeに送信します。各アイテムには、サポートチケット、通話記録、チャット会話など、スレッド化されたフィードバックのための会話部分を含めることができます。

POST https://amplitude.com/api/1/ai-feedback/ingest

curl -X POST 'https://amplitude.com/api/1/ai-feedback/ingest' \
  -u '{api_key}:{secret_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "YOUR_SOURCE_ID",
    "items": [
      {
        "unique_id": "review-789",
        "body": "The search feature is broken on mobile",
        "author": "Jane Doe",
        "user_id": "user-123",
        "created_at": "2026-03-15T10:30:00Z"
      }
    ]
  }'

ボディパラメータ

名前	概要
`source_id`	必須です。文字列（1～128文字）。フィードバックソースのソースID。ソースの詳細ページで、3つのドットメニュー、次に[設定]を選択するとあります。
`items`	必須です。配列（1～100個のアイテム）。取り込むフィードバックアイテム。

アイテムオブジェクト

名前	概要
`unique_id`	必須です。文字列（最大1024文字）。システム内のこのアイテムに対する安定した一意の識別子。アイテムの重複排除に使用されます。同じ`unique_id`を再度送信すると、既存のアイテムが更新されます。
`body`	オプションです。文字列（最大20,000文字）。フィードバックのテキスト。 Amplitudeによって既に取り込み済みのアイテムに会話パートを追加する際に、元のアイテムの詳細を再送信せずに新しい返信を追加する場合は、`body`を省略します。
`author`	オプションです。文字列（最大512文字）。このアイテムを記述した人の名前を表示します。
`email`	オプションです。文字列（最大512文字）。作成者の電子メールアドレス。有効なメールアドレスである必要があります。
`user_id`	オプションです。文字列（最大1024文字）。AmplitudeのユーザーID。 Analyticsの`user_id`フィールドに直接マップされます。フィードバックとユーザーの行動がリンクされ、フィードバックが行動データとともにコホートやチャートに表示されます。
`url`	オプションです。文字列（最大2048文字）。このアイテムに関連付けられたURL（ソースページやチケットリンクなど）。有効なURLである必要があります。
`created_at`	オプションです。ISO 8601の日時文字列。フィードバックの作成を示します。デフォルトはnowです。
`conversation_parts`	オプションです。配列（最大100個）。このアイテムに属するフォローアップメッセージまたは返信。

会話パートオブジェクト

各会話パートにはアイテムと同じフィールドが使用されますが、bodyが必須（最小1文字）となり、conversation_partsはネストできません。

名前	概要
`unique_id`	必須です。文字列（最大1024文字）。システム内のこの会話部分の安定した一意の識別子。重複排除に使用されます。
`body`	必須です。文字列（最大20,000文字）。テキストのコンテンツ。
`author`	オプションです。文字列（最大512文字）。この部分を記述した人の表示名。
`email`	オプションです。文字列（最大512文字）。作成者の電子メールアドレス。
`user_id`	オプションです。文字列（最大1024文字）。AmplitudeのユーザーID。これはAnalyticsの`user_id`フィールドに直接マップされます。
`url`	オプションです。文字列（最大2048文字）。この会話パートに関連付けられたURL。
`created_at`	オプションです。ISO 8601の日時文字列。フィードバックの作成を示します。デフォルトはnowです。

レスポンス

json

{
  "ingested": 2,
  "failed": 0,
  "errors": []
}

プロパティ	概要
`ingested`	正常に取り込まれたアイテムの数。
`failed`	検証または処理に失敗したアイテムの数。
`errors`	エラーオブジェクトの配列。各々に`unique_id`（文字列）と失敗内容を説明する`error`（文字列）が含まれます。

一部のアイテムが失敗した場合：

json

{
  "ingested": 1,
  "failed": 1,
  "errors": [
    {
      "unique_id": "ticket-9999",
      "error": "Body text exceeds maximum length"
    }
  ]
}

例

シンプルなフィードバック

NPSへの回答、アンケートへの回答、レビューなどのスタンドアロンのフィードバックを送信できます。各フィードバックが独自のアイテムであり、会話パートはありません。

curl -X POST 'https://amplitude.com/api/1/ai-feedback/ingest' \
  -u '{api_key}:{secret_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "YOUR_SOURCE_ID",
    "items": [
      {
        "unique_id": "review-789",
        "body": "The search feature is broken on mobile",
        "author": "Jane Doe",
        "user_id": "user-123",
        "created_at": "2026-03-15T10:30:00Z",
        "url": "https://feedback.example.com/reviews/789"
      },
      {
        "unique_id": "nps-response-4822",
        "body": "The onboarding flow was confusing and I almost gave up.",
        "author": "Bob Johnson",
        "created_at": "2026-03-20T15:00:00Z"
      }
    ]
  }'

回答付きのサポートチケット

最初のメッセージとその後の会話パートを含むサポートチケットを送信してください。最初のインポート後に既存のチケットに新しい返信を追加するには、「既存のアイテムに返信を追加する」を参照してください。

curl -X POST 'https://amplitude.com/api/1/ai-feedback/ingest' \
  -u '{api_key}:{secret_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "YOUR_SOURCE_ID",
    "items": [
      {
        "unique_id": "ticket-456",
        "body": "I need to export my dashboard data to Excel but I cannot find the option",
        "author": "Jane Doe",
        "user_id": "user-123",
        "created_at": "2026-03-10T09:00:00Z",
        "url": "https://support.example.com/tickets/456",
        "conversation_parts": [
          {
            "unique_id": "ticket-456-1",
            "body": "Thanks for reaching out! The export feature is under Settings > Data Export.",
            "author": "Support Agent",
            "email": "agent@company.com",
            "url": "https://support.example.com/tickets/456/1",
            "created_at": "2026-03-10T09:15:00Z"
          },
          {
            "unique_id": "ticket-456-2",
            "body": "I see it now, but it only exports CSV. We really need native Excel support.",
            "author": "Jane Doe",
            "user_id": "user-123",
            "created_at": "2026-03-10T09:20:00Z"
          }
        ]
      }
    ]
  }'

通話記録

通話記録を送信します。この場合、発話者の各ターンが会話パートとなります。アイテムはコール全体を表します。話者間で会話パーツを交互に変更し、トランスクリプトが自然な会話として読まれるようにします。通話記録の場合は、アイテム自体からbodyを省き、個々の会話パートのみを送信してください。

curl -X POST 'https://amplitude.com/api/1/ai-feedback/ingest' \
  -u '{api_key}:{secret_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "YOUR_SOURCE_ID",
    "items": [
      {
        "unique_id": "call-123",
        "author": "Sales Rep",
        "created_at": "2026-03-12T14:00:00Z",
        "url": "https://gong.io/calls/123",
        "conversation_parts": [
          {
            "unique_id": "call-123-1",
            "body": "How does that compare to the competition on pricing?",
            "author": "Buyer",
            "user_id": "user-456",
            "created_at": "2026-03-12T14:00:18Z"
          },
          {
            "unique_id": "call-123-2",
            "body": "Great question. Our base tier starts at...",
            "author": "Sales Rep",
            "created_at": "2026-03-12T14:00:22Z"
          }
        ]
      }
    ]
  }'

既存のアイテムに返信を追加する

すでに送信したアイテムに新しい会話パートを追加するには、同じunique_idでアイテムを再送信し、新しいパートのみを含めます。 bodyと元のアイテムの詳細は省いてください。unique_idと新しい会話パーツのみを送信します。

curl -X POST 'https://amplitude.com/api/1/ai-feedback/ingest' \
  -u '{api_key}:{secret_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "YOUR_SOURCE_ID",
    "items": [
      {
        "unique_id": "ticket-456",
        "conversation_parts": [
          {
            "unique_id": "ticket-456-3",
            "body": "We have added Excel export in the latest release. Can you try again?",
            "author": "Support Agent",
            "email": "agent@company.com",
            "created_at": "2026-03-11T10:00:00Z"
          }
        ]
      }
    ]
  }'

新しい会話パーツのみを含めます。Amplitudeにすでに取り込んだパートを再送する必要はありません。Amplitudeはunique_idを元にアップサートを実行するため、安全に再送信できます。

ステータスとエラーコード

コード	概要
`200 OK`	リクエストに成功しました。
`400 Bad Request`	要求本文が無効です。必須フィールドが不足しているか、検証エラーが発生しています。レスポンスには詳細な検証問題が含まれています。
`401 Unauthorized`	認証情報がありません。
`403 Forbidden`	認証情報が無効であるか、`source_id`によって識別されるソースがWebhookタイプではありません。
`404 Not Found`	指定された`source_id`に一致するソースは見つかりませんでした。

これは役に立ちましたか？