> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.5/basic-tutorials/guides/application/dev-chat/feedback-collection.md).

# 피드백 사유 수집

### 개요

채팅 앱에서 사용자가 답변에 남긴 **좋아요·싫어요 피드백의 사유를 어떻게 받을지** 정하는 기능입니다. 관리자는 채팅 앱을 만들거나 새 버전을 만들 때 좋아요와 싫어요 각각에 대해 사유를 받을지 여부(미수집·선택 수집·필수 수집)와 받는 방식(사용자 직접 입력·선택지 제공)을 정하고, 사용자는 그 설정에 따라 피드백 버튼을 누른 뒤 사유를 남깁니다. 수집된 사유는 채팅 상세의 **채팅 이용** 탭에서 확인합니다.

v1.9.5 이전에는 싫어요에만 사유 모달이 있었고 좋아요는 누르면 바로 반영됐습니다. v1.9.5부터 좋아요에도 같은 구조의 사유 수집이 생겼고, 두 축을 서로 다르게 설정할 수 있습니다.

진입 경로는 다음과 같습니다.

| 역할       | 경로                                                                         |
| -------- | -------------------------------------------------------------------------- |
| 설정       | **앱 > 채팅 앱 > `+ 채팅 앱 생성`** 또는 채팅 상세 > `새 버전 생성` > **② 인터랙션** > 「피드백 사유 수집」 |
| 설정 확인    | **앱 > 채팅 앱 > 채팅 상세 > 운영 정보** 탭 > 채팅 앱 설정 > 인터랙션                            |
| 수집 결과 확인 | **앱 > 채팅 앱 > 채팅 상세 > 채팅 이용** 탭 > 대화 행 클릭 > 우측 피드백 패널                       |
| 사용자 입력   | 사용자 채팅 화면의 답변 하단 좋아요·싫어요 버튼                                                |

<figure><img src="https://1442180325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVa1tsb4kzRuGbCJsMdPX%2Fuploads%2FPfZ6IsRLfVJItbyO2i8M%2Fchatfeedback_01_collection_section.png?alt=media&amp;token=a037ad35-c25d-4c2c-b8a4-dad84adb415f" alt=""><figcaption></figcaption></figure>

채팅 앱의 기본 생성 절차는 채팅 애플리케이션 만들기, 버전·배포 구조는 채팅 앱 다중 배포와 버전 관리 문서를 함께 참고해 주세요.

### 주요 개념

| 개념       | 설명                                                                  |
| -------- | ------------------------------------------------------------------- |
| 피드백 축    | 좋아요(긍정)와 싫어요(부정)를 가리킵니다. 두 축은 완전히 독립된 설정을 가집니다.                     |
| 사유 수집    | 피드백에 사유를 받을지 정하는 값입니다. `미수집` · `선택 수집` · `필수 수집` 중 하나입니다.           |
| 수집 방식    | 사유를 받는 방법입니다. `사용자 직접 입력`(주관식)과 `선택지 제공`(객관식) 중 하나입니다.              |
| 선택지      | 선택지 제공 방식에서 사용자에게 보여줄 항목 목록입니다. 최소 2개, 최대 10개입니다.                   |
| 기타 의견    | 선택지 목록 끝에 「기타」 항목을 추가하는 옵션입니다. 기타를 고르면 사용자가 이유를 직접 적습니다.            |
| 저장 시점 재현 | 피드백을 조회할 때, 설정이 바뀌거나 선택지가 삭제돼도 **저장 당시의 문구·수집 모드**를 그대로 보여주는 방식입니다. |

### 피드백 사유 수집 설정

채팅 앱 생성·새 버전 생성 화면의 **② 인터랙션** 단계에 있는 **「피드백 사유 수집」** 섹션에서 설정합니다. 섹션 안에는 좋아요·싫어요 블록이 같은 구조로 하나씩 들어 있습니다.

* **'좋아요' 피드백 사유 입력 설정**
* **'싫어요' 피드백 사유 입력 설정**

각 블록은 사유 수집 값을 고르는 세그먼트로 시작하고, `선택 수집`이나 `필수 수집`을 고르면 그 아래에 회색 카드가 펼쳐지면서 수집 방식과 선택지 입력이 나타납니다. `미수집`을 고르면 카드 전체가 사라집니다.

<figure><img src="https://1442180325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVa1tsb4kzRuGbCJsMdPX%2Fuploads%2FjDhX4ejHQkimhHhvrC6T%2Fchatfeedback_02_positive_optional.png?alt=media&amp;token=8c30acb0-29ac-408d-954a-ff861fd5c77f" alt=""><figcaption></figcaption></figure>

#### 사유 수집

| 값     | 사용자 화면 동작                                  |
| ----- | ------------------------------------------ |
| 미수집   | 버튼을 누르면 모달 없이 즉시 반영됩니다. 다시 누르면 바로 취소됩니다.   |
| 선택 수집 | 사유 모달이 뜨지만, 아무것도 입력·선택하지 않아도 `제출`할 수 있습니다. |
| 필수 수집 | 사유 모달이 뜨고, 입력하거나 선택해야 `제출`할 수 있습니다.        |

라벨 옆 도움말에는 다음 설명이 표시됩니다.

```
· 미수집 : 피드백 선택 사유를 받지 않습니다.
· 선택 수집 : 사유를 입력/선택하지 않아도 피드백이 저장됩니다.
· 필수 수집 : 사유를 입력/선택해야만 피드백이 저장됩니다.
```

#### 수집 방식

`선택 수집`·`필수 수집`일 때만 나타납니다.

| 값         | 설명                     |
| --------- | ---------------------- |
| 사용자 직접 입력 | 사용자가 의견을 주관식으로 적습니다.   |
| 선택지 제공    | 관리자가 등록한 선택지 중에서 고릅니다. |

#### 선택지 등록

`선택지 제공`을 고르면 **선택지** 표가 나타납니다.

| 항목     | 규칙                                                           |
| ------ | ------------------------------------------------------------ |
| 개수     | 최소 2개, 최대 10개 (`최대 10개까지 추가할 수 있습니다.`)                       |
| 글자 수   | 1개당 최대 128자, 입력 중 글자 수 카운터 표시                                |
| 플레이스홀더 | `예) 질문과 관련 없는 답변이에요`                                         |
| 행 삭제   | 2행 이하일 때는 삭제 아이콘이 비활성화됩니다                                    |
| 전체 삭제  | 행이 2개를 넘을 때만 표 우측 상단에 `전체 삭제 (N)` 버튼이 보이며, 누르면 빈 2행으로 되돌아갑니다 |

표 아래의 **「주관식으로 기타 의견 받기」** 를 체크하면 선택지 목록 끝에 「기타」 항목이 붙습니다. 사용자가 기타를 고르면 이유를 직접 적는 입력란이 열립니다. 이 항목은 **기본으로 체크되어 있으며**, 기타를 받지 않으려면 직접 해제합니다.

<figure><img src="https://1442180325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVa1tsb4kzRuGbCJsMdPX%2Fuploads%2Fgit-blob-40774c85c10fe4be47a5a426645f122e0655f1e6%2Fchatfeedback_03_choice_options.png?alt=media" alt=""><figcaption></figcaption></figure>

저장 시 선택지를 비워 두거나 2개 미만이면 다음 문구로 막힙니다.

* `선택지를 입력해 주세요.`
* `선택지를 2개 이상 입력해 주세요.`

검증에 실패하면 화면이 실제로 틀린 축(좋아요 또는 싫어요)까지 자동으로 스크롤됩니다.

#### 기본값과 승계 규칙

설정을 건드리지 않았을 때의 초기값은 들어온 경로에 따라 다릅니다.

| 경로                        | 좋아요   | 싫어요   |
| ------------------------- | ----- | ----- |
| 채팅 앱 신규 생성                | 선택 수집 | 필수 수집 |
| 새 버전 생성 (이전 버전에 값이 없는 경우) | 미수집   | 필수 수집 |

새 버전 생성은 기본적으로 **이전 버전 값을 그대로 승계**하며, 위 값은 승계할 값이 없을 때(기능 적용 이전에 만들어진 버전)의 폴백입니다. 좋아요를 `미수집`으로 두는 이유는 기존 동작(좋아요는 모달 없이 즉시 반영)을 그대로 유지하기 위해서입니다.

> **설정을 바꾸려면 새 버전을 만들어야 합니다.** 운영 중인 버전의 피드백 설정을 그 자리에서 수정할 수는 없습니다.

#### 설정값 확인

채팅 상세의 **운영 정보** 탭 > 채팅 앱 설정 > 인터랙션에서 각 축의 설정값을 확인합니다. 값은 `선택 수집` `사용자 직접 입력`처럼 **태그 두 개**로 나란히 표시되며, `미수집`이면 수집 방식이 의미가 없어 모드 태그만 표시됩니다. `선택지 제공`이면 저장 시점의 선택지 목록과 기타 사용 여부를 펼쳐 볼 수 있습니다.

### 사용자 화면 — 피드백 남기기

사용자 채팅 화면에서 답변 아래의 **답변에 만족**(좋아요) · **답변에 불만족**(싫어요) 버튼을 누릅니다.

해당 축이 `미수집`이면 모달 없이 즉시 반영되고, `선택 수집`·`필수 수집`이면 **「피드백」** 모달이 열립니다(버튼은 `취소` · `제출`). 좋아요·싫어요는 같은 모달을 쓰며, 누른 버튼에 해당하는 축의 설정이 적용됩니다.

<figure><img src="https://1442180325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVa1tsb4kzRuGbCJsMdPX%2Fuploads%2Fy5BVLnDOjKuxoGM4s4gK%2Fchatfeedback_04_user_modal.png?alt=media&amp;token=44dcb0ea-a5ff-4dd1-8a2b-4704af9b3af9" alt=""><figcaption></figcaption></figure>

#### 사용자 직접 입력 방식

의견 입력란(`답변에 대한 의견을 자유롭게 남겨 주세요`)에 최대 256자까지 적습니다. 글자 수 카운터가 함께 표시됩니다.

#### 선택지 제공 방식

등록된 선택지를 체크합니다. 항목마다 `선택한 이유를 입력해 주세요` 입력란(최대 256자)이 있지만, **항목별 이유는 어떤 설정에서도 필수가 아닙니다.** 기타를 체크한 경우에만 이유 입력이 필수입니다. 「주관식으로 기타 의견 받기」를 끈 설정에서는 모달에 「기타」 항목이 나타나지 않습니다.

#### `제출` 활성 조건

| 사유 수집 | 수집 방식     | 제출 조건                       |
| ----- | --------- | --------------------------- |
| 선택 수집 | 사용자 직접 입력 | 아무것도 적지 않아도 제출 가능           |
| 선택 수집 | 선택지 제공    | 아무것도 고르지 않아도 제출 가능          |
| 필수 수집 | 사용자 직접 입력 | 의견을 1자 이상 입력해야 제출 가능        |
| 필수 수집 | 선택지 제공    | 선택지 또는 기타를 1개 이상 체크해야 제출 가능 |

기타를 체크했다면 수집 모드와 관계없이 기타 이유를 입력해야 제출됩니다.

#### 피드백 취소

이미 누른 버튼을 다시 누르면 피드백을 취소합니다. 동작은 좋아요·싫어요가 같습니다.

* 해당 축이 `미수집`이면 지울 사유가 없어 **즉시 취소**됩니다.
* `선택 수집`·`필수 수집`이면 저장된 사유를 그대로 보여주는 **「피드백 삭제」** 확인 모달을 거칩니다(버튼은 `취소` · `삭제`). 이전에 체크한 선택지와 입력한 이유가 그대로 표시되므로, 무엇을 지우는지 확인한 뒤 삭제할 수 있습니다.

<figure><img src="https://1442180325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVa1tsb4kzRuGbCJsMdPX%2Fuploads%2FuTKLU35QIGLaY8D5jkKK%2Fchatfeedback_05_user_delete_modal.png?alt=media&amp;token=43571a18-7dea-44b4-9d2e-e8e7620f8278" alt=""><figcaption></figcaption></figure>

> 관리자 화면에 내장된 채팅 로그(읽기 전용) 화면에서는 피드백 버튼이 보이지만 누를 수 없습니다. 다른 사용자의 피드백을 바꾸지 못하도록 막아 둔 것입니다.

### 수집된 사유 확인

채팅 상세의 **채팅 이용** 탭 목록에는 대화별로 **「긍정 피드백」·「부정 피드백」 건수** 컬럼이 있습니다. 대화 행을 누르면 전체 화면 팝업이 열리고, 좌측에 대화 내용, 우측에 **피드백** 패널이 나타납니다.

패널 상단 세그먼트로 전체·긍정·부정을 걸러 볼 수 있고, 행마다 긍·부정 배지와 일시, 수집된 사유가 표시됩니다. 한 번에 10건씩 보며 페이지로 넘깁니다. 행을 누르면 좌측 대화에서 해당 메시지가 강조되고, `>>` 버튼으로 패널을 접을 수 있습니다. 피드백이 없는 대화는 「사용자 피드백이 없습니다.」로 표시됩니다.

<figure><img src="https://1442180325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVa1tsb4kzRuGbCJsMdPX%2Fuploads%2FnQnckuz5rxeZ88iXv4yT%2Fchatfeedback_06_feedback_panel.png?alt=media&amp;token=cdb223c6-8d56-4f7e-866e-bd53ce964446" alt=""><figcaption></figcaption></figure>

사유는 **저장 시점 기준으로 재현**됩니다. 설정을 바꾸거나 선택지를 지운 뒤에도 과거 피드백은 저장 당시 문구 그대로 보이며, 삭제됐다는 표식은 붙지 않습니다.

| 상태                            | 표시                              |
| ----------------------------- | ------------------------------- |
| 사유가 수집된 건                     | 항목명과 사유를 함께 표시 (기타 항목은 「기타」 라벨) |
| `미수집` 설정으로 저장된 건              | `사유 수집 안 함`                     |
| `선택 수집`·`필수 수집`인데 사유를 적지 않은 건 | `-`                             |
| 이 기능 적용 이전에 쌓인 건              | 사유 영역을 표시하지 않음                  |

사용자가 고른 선택지는 저장할 때 항목 식별자와 문구를 함께 남깁니다. 「기타」는 문구가 아니라 별도 플래그로 구분하므로, 관리자가 `기타`라는 이름의 선택지를 직접 등록해도 서로 섞이지 않습니다.

| 작업           | 가능한 사용자                    |
| ------------ | -------------------------- |
| 피드백 사유 수집 설정 | 채팅 앱 생성·새 버전 생성 권한이 있는 관리자 |
| 수집된 사유 조회    | 해당 채팅 앱 읽기 권한이 있는 관리자      |
| 피드백 입력·취소    | 해당 채팅 앱을 이용하는 사용자 본인       |

### 오류·예외 처리

| 상황                               | 화면     | 표시 문구                                |
| -------------------------------- | ------ | ------------------------------------ |
| 선택지를 비운 채 저장                     | 관리자 설정 | 선택지를 입력해 주세요.                        |
| 선택지가 2개 미만                       | 관리자 설정 | 선택지를 2개 이상 입력해 주세요.                  |
| 필수 수집 + 선택지 제공인데 아무것도 체크하지 않고 제출 | 사용자 모달 | 하나 이상의 항목을 선택해 주세요.                  |
| 기타를 체크하고 이유를 비운 채 제출             | 사용자 모달 | 기타 의견을 입력해 주세요.                      |
| 필수 수집 + 사용자 직접 입력인데 의견을 비운 채 제출  | 사용자 모달 | 의견을 입력해 주세요.                         |
| 피드백 저장·취소 요청 실패                  | 사용자 채팅 | 서버 오류 메시지 토스트가 뜨고 버튼 상태가 원래대로 되돌아갑니다 |

본문이 길어 오류 문구가 화면 밖으로 밀리는 경우, 오류가 난 입력란이 보이는 위치로 자동으로 끌어와집니다.

### 사용 시나리오

#### 좋아요는 가볍게, 싫어요는 자세히 받고 싶은 경우

좋아요를 `미수집`으로, 싫어요를 `필수 수집` + `선택지 제공`으로 설정합니다. 사용자는 좋아요를 누를 때 방해받지 않고, 싫어요를 누를 때만 사유 모달을 만납니다.

#### 긍정 피드백의 이유도 모으고 싶은 경우

좋아요를 `선택 수집` + `선택지 제공`으로 설정하고 선택지를 등록합니다. 사용자는 사유를 고르지 않고도 좋아요를 남길 수 있어 부담이 없고, 남긴 사람의 사유는 피드백 패널에 쌓입니다.

#### 정해진 범주로만 사유를 모으고 싶은 경우

`선택지 제공`을 고르고 분류 체계에 맞는 선택지를 등록합니다. 범주를 벗어난 의견도 받으려면 「주관식으로 기타 의견 받기」를 함께 체크합니다.

#### 운영 중에 선택지를 바꾸고 싶은 경우

새 버전을 만들어 선택지를 수정한 뒤 배포합니다. 이미 쌓인 피드백은 저장 시점 문구로 계속 표시되므로 과거 집계가 흔들리지 않습니다.

#### 피드백 패널에 사유가 `-`로만 보이는 경우

해당 건은 `선택 수집` 설정에서 사용자가 사유를 남기지 않고 제출한 경우입니다. 사유 입력을 강제하려면 새 버전에서 `필수 수집`으로 바꿉니다.

#### 피드백 패널에 `사유 수집 안 함`이라고 표시되는 경우


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://genos-docs.gitbook.io/default/v1.9.5/basic-tutorials/guides/application/dev-chat/feedback-collection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.