AI 피드백 API

요청 요구 사항 및 제한

모든 엔드포인트는 HTTP 기본 인증을 사용합니다. 프로젝트의 API 키를 사용자 이름으로 사용하고 비밀 키를 암호로 사용하십시오.
요청 본문은 Content-Type: application/json을(를) 포함한 JSON 형이어야 합니다.
최대 페이로드 크기는 5MB입니다.
각 요청에는 1~100개의 피드백 항목이 허용됩니다.
Amplitude는 소스 내에서 unique_id을(를) 기준으로 항목 및 대화 부분의 중복을 제거합니다. Amplitude는 기존 레코드를 업서트하므로 동일한 데이터를 두 번 전송하는 것이 안전합니다.
기존 항목에 새 대화 부분을 추가하려면 동일한 unique_id을(를) 사용하여 항목을 다시 전송하고 새 부분을 포함하십시오. Amplitude는(unique_id와 일치하는) 기존 부분을 업서트하고 새 부분을 추가합니다.

소스 ID 찾기

웹후크 소스에 대한 source_id을(를) 찾으려면 AI 피드백의 소스 세부 정보 페이지로 이동하여 점 세 개 메뉴를 선택한 다음 설정을 선택합니다. 이 페이지에는 소스 ID와 예제 요청이 표시됩니다.

EU 데이터 상주

EU 데이터 상주의 경우 https://amplitude.com 대신 https://eu.amplitude.com을(를) 기본 URL로 사용하십시오. 예를 들면 다음과 같습니다.

피드백 수집: 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입니다. 소스 세부 정보 페이지에서 세 개의 점 메뉴를 선택한 다음 설정을 선택하여 이 정보를 확인하십시오.
`items`	필수입니다. 배열(1–100개 항목). 수집할 피드백 항목입니다.

항목 객체

이름	설명
`unique_id`	필수입니다. 문자열(최대 1024자). 시스템에서 이 항목에 대한 안정적이고 고유한 식별자입니다. 항목의 중복 제거에 사용됩니다. 동일한 `unique_id`을(를) 다시 전송하면 기존 항목이 업데이트됩니다.
`body`	선택 사항입니다. 문자열(최대 20,000자). 피드백 텍스트입니다. 원본 항목 세부 정보를 다시 보내지 않고 새 회신을 추가하려면, Amplitude가 이미 수집한 항목에 대화 부분을 추가할 때 `body`을(를) 생략하십시오.
`author`	선택 사항입니다. 문자열(최대 512자). 이 항목을 작성한 사람의 이름을 표시합니다.
`email`	선택 사항입니다. 문자열(최대 512자). 작성자의 이메일 주소입니다. 유효한 이메일이어야 합니다.
`user_id`	선택 사항입니다. 문자열(최대 1024자). Amplitude 사용자 ID입니다. 분석의 `user_id` 필드에 직접 매핑되며, 이는 피드백을 사용자 행동에 연결하고 피드백을 행동 데이터와 함께 코호트 및 차트에 표시합니다.
`url`	선택 사항입니다. 문자열(최대 2048자). 이 항목과 연관된 URL(예: 소스 페이지 또는 티켓 링크)입니다. 유효한 URL이어야 합니다.
`created_at`	선택 사항입니다. ISO 8601 날짜/시간 문자열입니다. 피드백의 생성을 나타냅니다. 기본값은 지금입니다.
`conversation_parts`	선택 사항입니다. 어레이(최대 100개). 이 항목에 속하는 후속 메시지 또는 회신입니다.

대화 부분 객체

각 대화 부분은 body이(가) 필수(최소 1자)이고 conversation_parts이(가) 중첩될 수 없다는 점을 제외하고 항목과 동일한 필드를 사용합니다.

이름	설명
`unique_id`	필수입니다. 문자열(최대 1024자). 시스템에서 이 대화 부분에 대한 안정적이고 고유한 식별자입니다. 데이터 중복 제거에 사용됩니다.
`body`	필수입니다. 문자열(최대 20,000자). 텍스트 콘텐츠입니다.
`author`	선택 사항입니다. 문자열(최대 512자). 이 부분을 작성한 사람의 표시 이름입니다.
`email`	선택 사항입니다. 문자열(최대 512자). 작성자의 이메일 주소입니다.
`user_id`	선택 사항입니다. 문자열(최대 1024자). Amplitude 사용자 ID입니다. 이 정보는 분석의 `user_id` 필드에 직접 매핑됩니다.
`url`	선택 사항입니다. 문자열(최대 2048자). 이 대화 부분과 연결된 URL입니다.
`created_at`	선택 사항입니다. ISO 8601 날짜/시간 문자열입니다. 피드백의 생성을 나타냅니다. 기본값은 지금입니다.

응답

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`에서 식별한 소스가 웹후크 유형이 아닙니다.
`404 Not Found`	제공된 `source_id`와(과) 일치하는 소스를 찾을 수 없습니다.

이 내용이 도움이 되었나요?