Feedback API - theseeker CRM 문서

API 레퍼런스

Feedback API

조직의 피드백을 조회하고 프로젝트 키로 전송하는 경계를 설명합니다.

GET /api/v1/feedback

피드백 목록 조회에는 admin:read 또는 feedback:read가 필요합니다.

bash

curl -sS https://crm.theseeker.io/api/v1/feedback \
  -H "Authorization: Bearer $THESEEKER_API_KEY"

응답은 인증 키가 허용하는 조직 또는 프로젝트 범위 안에서 반환됩니다.

이벤트 전송

피드백 전송은 프로젝트 ingest 경로를 사용합니다. Status SDK에서는 sendFeedback으로 호출합니다.

typescript

await status.sendFeedback({
  uid: "user-123",
  content: "검색 결과가 느립니다.",
  fields: { plan: "pro" },
});

이 요청에는 프로젝트 키와 SDK가 생성하는 서명 헤더가 필요합니다. 관리 API Bearer 키를 ingest HMAC 키 대신 사용하지 마세요.

필드

필드	설명
`uid`	호출자가 정한 사용자 식별자
`content`	피드백 본문
`fields`	검색 가능한 추가 필드
`extra`	부가 문맥

응답 필드

GET /api/v1/feedback은 feedbacks 배열과 페이지네이션용 nextCursor를 반환합니다. 각 항목은 기존 ID, 사용자 ID, 본문, 발생·수신 시각, fields, extra에 다음 필드를 추가로 포함합니다.

필드	형식	설명
`status`	string	`new`, `in_progress`, `resolved`, `closed`
`tags`	string[]	피드백 분류 태그
`kind`	string	`feedback`, `nps`, `csat`
`source`	string	`sdk`, `widget`, `survey`
`score`	number 또는 null	NPS/CSAT 점수
`pageUrl`	string 또는 null	응답 페이지 URL
`contactEmail`	string 또는 null	제출자가 제공한 연락 이메일
`contact`	string 또는 null	위젯 자유 텍스트 연락처 (`contactMode: "text"`일 때, 최대 120자)
`sessionId`	string 또는 null	연결된 분석 세션
`propertyId`	string 또는 null	연결된 분석 프로퍼티
`relatedIssueIds`	string[]	연결된 에러 이슈 ID
`browser`, `os`, `device`	string 또는 null	방문자 환경 정보
`hasScreenshot`	boolean	기존 스크린샷 첨부 존재 여부(레거시 데이터 조회용)
`updatedAt`	ISO 시각 또는 null	마지막 갱신 시각

위젯 제출

공개 위젯은 POST /api/feedback/widget으로 제출합니다. 기존 JSON 형식은 계속 사용할 수 있으며, 위젯은 이미지가 있을 때 multipart/form-data를 사용합니다. multipart에는 JSON 문자열인 payload 파트와 이미지 파일용 0~4개의 image 파트를 넣습니다. 스크린샷 캡처·업로드는 종료되었으며 multipart screenshot 파트나 JSON screenshot 필드를 보내면 종류와 관계없이 400 SCREENSHOT_DISABLED를 반환합니다. 기존 스크린샷과 hasScreenshot 조회는 유지됩니다. config는 GET /api/feedback/widget/config?key=fbw_…로 조회합니다. 응답에는 표시 방식 displayMode(launcher, inline, manual)와 이미지 첨부 허용 여부 imageUploadEnabled가 포함됩니다. 허용 도메인에서 온 Origin이 필요합니다. 설정과 제출의 CORS 응답은 허용 Origin에 한하며, preflight는 POST, OPTIONS와 Content-Type을 허용합니다.

JSON payload에는 key, kind, content, pageUrl을 보내고 선택적으로 contactEmail, contact, uid, surveyId, score를 포함합니다. 자유 텍스트 연락처 contact는 최대 120자입니다. 일반 피드백 본문은 1~~5,000자이며 설문은 0~~5,000자입니다. NPS 점수는 0~~10, CSAT은 1~~5입니다. JSON 요청 최대 크기는 2 MiB이고 multipart 요청은 최대 9 MiB입니다. 각 multipart 이미지는 2 MiB(2,097,152바이트) 이하여야 합니다. 파일 형식은 이름이나 Content-Type이 아니라 파일 시그니처로 판별하며 PNG, JPEG, WebP, GIF를 지원합니다. IP/key 조합당 10분 10회, key당 10분 100회로 제한됩니다. 성공 시 201 {"id":"…"}를 반환합니다. 설문 제출은 현재 활성 설문 ID와 유형이 일치해야 합니다. SDK·/v1/feedback 는 이미지를 받지 않습니다.

모바일 앱 모드

앱 요청은 Origin 없이 X-TheSeeker-App: com.example.app 헤더를 보냅니다. pageUrl은 app://<appId>/<path> 형식이어야 하며 URL의 앱 ID는 헤더 값과 일치해야 합니다. 예: app://com.example.app/settings.

선택 필드 client는 앱 환경 정보를 전달합니다. platform은 ios 또는 android, osVersion과 appVersion은 최대 32자, deviceModel은 최대 64자, deviceType은 phone 또는 tablet입니다.

오류 코드	HTTP	설명
`APP_NOT_ALLOWED`	403	앱 ID가 위젯의 허용 앱 목록에 없습니다.
`VALIDATION_ERROR`	400	본문이 잘못됐거나 `pageUrl`의 앱 ID가 헤더와 다릅니다.

요청 본문이 허용 크기를 넘으면 413 PAYLOAD_TOO_LARGE, 이미지 하나가 2 MiB를 넘으면 413 IMAGE_TOO_LARGE를 반환합니다. 400 오류 코드는 INVALID_IMAGE, TOO_MANY_IMAGES, IMAGES_DISABLED, SCREENSHOT_DISABLED, VALIDATION_ERROR, BAD_REQUEST입니다.

위젯 설정 API

관리 API 키로 프로젝트의 공개 피드백 위젯을 조회하거나 설정합니다. 공개 키 재발급은 API에서 지원하지 않습니다.

GET /api/v1/feedback/widget

필요 scope는 admin:read 또는 feedback:read입니다. 조직 키는 projectSlug가 필수입니다. 프로젝트에 묶인 키는 자신의 프로젝트만 조회할 수 있으며, 다른 slug를 지정하면 403 project_forbidden을 반환합니다.

bash

curl -sS 'https://crm.theseeker.io/api/v1/feedback/widget?projectSlug=my-project' \
  -H "Authorization: Bearer $THESEEKER_API_KEY"

설정 전 응답은 {"widget":null,"install":null}입니다. 설정이 있으면 widget에는 id, projectId, publicKey, enabled, allowedDomains, imageUploadEnabled, displayMode, position, buttonLabel, accent, theme, appearance, texts, localizedTexts, contactMode, updatedAt가 포함됩니다. theme은 light|dark|system|auto, appearance는 테마별 팔레트와 반경·글꼴, texts는 위젯 문구입니다. install에는 스크립트 URL, 문서 URL, 현재 표시 방식의 snippet, 그리고 launcher, inline, manual 스니펫이 들어갑니다.

응답 필드	형식	설명
`theme`	`light` \| `dark` \| `system` \| `auto`	고정 테마, OS 테마 또는 페이지 테마 감지 방식
`appearance`	object	`light`, `dark` 색상 팔레트와 `radius`, `font`
`texts`	object	위젯 제목, 설명, 입력 레이블·힌트, 버튼과 완료 문구(기본 언어 ko)
`localizedTexts`	object	언어별 문구. 현재 `en` 만 지원하며 `texts`와 같은 키에 `buttonLabel`을 더합니다
`contactMode`	`email` \| `text` \| `hidden`	이메일, 자유 텍스트 연락처 또는 연락처 입력 숨김
`allowedApps`	string[]	허용된 iOS 번들 ID 또는 Android 패키지 이름 목록. `allowedDomains`와 별도이며 최대 20개입니다.

install.reactNative에는 React Native SDK 설치 정보를 담습니다.

필드	형식	설명
`packageName`	string	SDK 패키지 이름
`installCommand`	string	설치 명령
`snippet`	string	Provider 예시. 등록된 첫 앱 ID를 반영합니다.

PATCH /api/v1/feedback/widget

필요 scope는 admin:write입니다. JSON 본문에 projectSlug와 설정할 필드를 하나 이상 보냅니다. projectSlug는 조직 키에서 필수이며 프로젝트에 묶인 키는 생략할 수 있습니다. theme은 light|dark|system|auto, contactMode는 email|text|hidden입니다. appearance는 light·dark 팔레트(키 accent, accentText, background, text, mutedText, border는 #rrggbb), radius(panel 정수 0~~32px, field·button 정수 0~~24px), font(default|inherit)를 받습니다. texts는 title(60자), description(200자), contentLabel(30자), contentPlaceholder(120자), contactLabel(40자), contactPlaceholder(120자), submitLabel·cancelLabel(각 20자), thanks(80자)를 받습니다. appearance와 texts는 깊은 병합되며 생략한 키는 유지됩니다. 키에 null을 보내면 해당 키가 기본값으로 초기화되고, 그룹을 null로 보내면 해당 그룹 전체를 초기화합니다. 알 수 없는 키, 잘못된 #rrggbb 색상, 범위를 벗어난 값과 빈 설정 요청은 400으로 거부됩니다. 생략한 다른 설정은 유지되며, 아직 설정이 없으면 기본값으로 생성합니다.

필드	형식·허용값	제한·동작
`theme`	`light` \| `dark` \| `system` \| `auto`	생략 시 기존 값 유지
`appearance.light`, `appearance.dark`	팔레트 object	`accent`, `accentText`, `background`, `text`, `mutedText`, `border`는 각각 `#rrggbb`; 키별 깊은 병합, `null`은 기본값
`appearance.radius`	object	`panel`: 정수 0부터 32px까지, `field`·`button`: 정수 0부터 24px까지; 깊은 병합, 키 또는 그룹 `null`은 기본값
`appearance.font`	`default` \| `inherit`	`null`은 기본값
`texts`	object	`title` 60자, `description` 200자, `contentLabel` 30자, `contentPlaceholder` 120자, `contactLabel` 40자, `contactPlaceholder` 120자, `submitLabel`·`cancelLabel` 각 20자, `thanks` 80자; 키별 병합, 빈 문자열 또는 `null`은 기본값
`localizedTexts.en`	object	`texts`와 같은 키와 한도에 `buttonLabel`(24자)을 더한 영어 문구; 키별 병합, 빈 문자열 또는 키 `null`은 영어 기본 문구, `en: null`은 영어 문구 전체 초기화
`contactMode`	`email` \| `text` \| `hidden`	생략 시 기존 값 유지
기타 기존 설정	`enabled`, `allowedDomains`, `allowedApps`, `displayMode`, `position`, `buttonLabel`, `accent`, `imageUploadEnabled`	기존 필드와 같은 검증·부분 변경 규칙. 허용 도메인과 앱 목록은 독립적으로 교체하며 한 목록만 보내면 다른 목록은 유지합니다.

하위 호환을 위해 REST PATCH만 screenshotEnabled boolean을 받되 무시하며 저장·응답하지 않습니다. 이 필드만 보내면 실제 변경할 설정이 없어 400 VALIDATION_ERROR와 Provide at least one widget setting 메시지를 반환합니다. MCP 입력에는 이 필드가 없습니다.

bash

curl -sS -X PATCH https://crm.theseeker.io/api/v1/feedback/widget \
  -H "Authorization: Bearer $THESEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectSlug":"my-project","enabled":true,"allowedDomains":["example.com"]}'

잘못된 JSON은 400 BAD_REQUEST, 값 검증 실패나 설정 누락은 400 VALIDATION_ERROR, 범위 밖 프로젝트는 403 project_forbidden, 찾을 수 없는 프로젝트나 위젯은 404 오류를 반환합니다.

오류

조회 인증 실패는 401, scope 부족은 403, 잘못된 요청은 400입니다. secret과 개인정보가 서버 로그나 피드백 본문에 섞이지 않도록 호출 전에 정제하세요.

이 페이지가 도움이 되었나요?

API 레퍼런스

Feedback API

조직의 피드백을 조회하고 프로젝트 키로 전송하는 경계를 설명합니다.

GET /api/v1/feedback

피드백 목록 조회에는 admin:read 또는 feedback:read가 필요합니다.

bash

curl -sS https://crm.theseeker.io/api/v1/feedback \
  -H "Authorization: Bearer $THESEEKER_API_KEY"

응답은 인증 키가 허용하는 조직 또는 프로젝트 범위 안에서 반환됩니다.

이벤트 전송

피드백 전송은 프로젝트 ingest 경로를 사용합니다. Status SDK에서는 sendFeedback으로 호출합니다.

typescript

await status.sendFeedback({
  uid: "user-123",
  content: "검색 결과가 느립니다.",
  fields: { plan: "pro" },
});

이 요청에는 프로젝트 키와 SDK가 생성하는 서명 헤더가 필요합니다. 관리 API Bearer 키를 ingest HMAC 키 대신 사용하지 마세요.

필드

필드	설명
`uid`	호출자가 정한 사용자 식별자
`content`	피드백 본문
`fields`	검색 가능한 추가 필드
`extra`	부가 문맥

응답 필드

필드	형식	설명
`status`	string	`new`, `in_progress`, `resolved`, `closed`
`tags`	string[]	피드백 분류 태그
`kind`	string	`feedback`, `nps`, `csat`
`source`	string	`sdk`, `widget`, `survey`
`score`	number 또는 null	NPS/CSAT 점수
`pageUrl`	string 또는 null	응답 페이지 URL
`contactEmail`	string 또는 null	제출자가 제공한 연락 이메일
`contact`	string 또는 null	위젯 자유 텍스트 연락처 (`contactMode: "text"`일 때, 최대 120자)
`sessionId`	string 또는 null	연결된 분석 세션
`propertyId`	string 또는 null	연결된 분석 프로퍼티
`relatedIssueIds`	string[]	연결된 에러 이슈 ID
`browser`, `os`, `device`	string 또는 null	방문자 환경 정보
`hasScreenshot`	boolean	기존 스크린샷 첨부 존재 여부(레거시 데이터 조회용)
`updatedAt`	ISO 시각 또는 null	마지막 갱신 시각

위젯 제출

모바일 앱 모드

오류 코드	HTTP	설명
`APP_NOT_ALLOWED`	403	앱 ID가 위젯의 허용 앱 목록에 없습니다.
`VALIDATION_ERROR`	400	본문이 잘못됐거나 `pageUrl`의 앱 ID가 헤더와 다릅니다.

위젯 설정 API

관리 API 키로 프로젝트의 공개 피드백 위젯을 조회하거나 설정합니다. 공개 키 재발급은 API에서 지원하지 않습니다.

GET /api/v1/feedback/widget

bash

curl -sS 'https://crm.theseeker.io/api/v1/feedback/widget?projectSlug=my-project' \
  -H "Authorization: Bearer $THESEEKER_API_KEY"

응답 필드	형식	설명
`theme`	`light` \| `dark` \| `system` \| `auto`	고정 테마, OS 테마 또는 페이지 테마 감지 방식
`appearance`	object	`light`, `dark` 색상 팔레트와 `radius`, `font`
`texts`	object	위젯 제목, 설명, 입력 레이블·힌트, 버튼과 완료 문구(기본 언어 ko)
`localizedTexts`	object	언어별 문구. 현재 `en` 만 지원하며 `texts`와 같은 키에 `buttonLabel`을 더합니다
`contactMode`	`email` \| `text` \| `hidden`	이메일, 자유 텍스트 연락처 또는 연락처 입력 숨김
`allowedApps`	string[]	허용된 iOS 번들 ID 또는 Android 패키지 이름 목록. `allowedDomains`와 별도이며 최대 20개입니다.

install.reactNative에는 React Native SDK 설치 정보를 담습니다.

필드	형식	설명
`packageName`	string	SDK 패키지 이름
`installCommand`	string	설치 명령
`snippet`	string	Provider 예시. 등록된 첫 앱 ID를 반영합니다.

PATCH /api/v1/feedback/widget

필드	형식·허용값	제한·동작
`theme`	`light` \| `dark` \| `system` \| `auto`	생략 시 기존 값 유지
`appearance.light`, `appearance.dark`	팔레트 object	`accent`, `accentText`, `background`, `text`, `mutedText`, `border`는 각각 `#rrggbb`; 키별 깊은 병합, `null`은 기본값
`appearance.radius`	object	`panel`: 정수 0부터 32px까지, `field`·`button`: 정수 0부터 24px까지; 깊은 병합, 키 또는 그룹 `null`은 기본값
`appearance.font`	`default` \| `inherit`	`null`은 기본값
`texts`	object	`title` 60자, `description` 200자, `contentLabel` 30자, `contentPlaceholder` 120자, `contactLabel` 40자, `contactPlaceholder` 120자, `submitLabel`·`cancelLabel` 각 20자, `thanks` 80자; 키별 병합, 빈 문자열 또는 `null`은 기본값
`localizedTexts.en`	object	`texts`와 같은 키와 한도에 `buttonLabel`(24자)을 더한 영어 문구; 키별 병합, 빈 문자열 또는 키 `null`은 영어 기본 문구, `en: null`은 영어 문구 전체 초기화
`contactMode`	`email` \| `text` \| `hidden`	생략 시 기존 값 유지
기타 기존 설정	`enabled`, `allowedDomains`, `allowedApps`, `displayMode`, `position`, `buttonLabel`, `accent`, `imageUploadEnabled`	기존 필드와 같은 검증·부분 변경 규칙. 허용 도메인과 앱 목록은 독립적으로 교체하며 한 목록만 보내면 다른 목록은 유지합니다.

bash

curl -sS -X PATCH https://crm.theseeker.io/api/v1/feedback/widget \
  -H "Authorization: Bearer $THESEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectSlug":"my-project","enabled":true,"allowedDomains":["example.com"]}'

오류

이 페이지가 도움이 되었나요?