> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage feedback templates

Create, configure, and manage feedback templates in Studio. A feedback template defines a survey that your agents present to end users, so every agent that asks the same question produces the same, comparable number.

## What's a feedback template

A feedback template is a project-level definition of one survey. It holds a single question, a single rating control, and the supporting text end users see. It also defines whether the survey runs on voice calls, and whether it includes a follow-up question or a comment box.

Because the template owns the question and the rating control, every agent that references it collects the same measurement. Agents reference the template by name; they don't redefine it.

A template controls the following.

| Element                | What it defines                                                      |
| ---------------------- | -------------------------------------------------------------------- |
| **Survey type**        | The rating control and the scoring range. Fixed after creation.      |
| **Survey design**      | The question, submit button, thank-you message, and scale labels.    |
| **Follow-up question** | An optional second question, asked only when a condition matches.    |
| **Comment box**        | An optional free-text field shown alongside the rating.              |
| **Voice behavior**     | Whether the survey runs on voice calls, and how the caller responds. |

Creating a template doesn't start collecting feedback. To collect responses, you reference the template from an agent and deploy the project, or you submit responses through the public API.

<Note>Until you create at least one template, the [Feedback Insights](/agent-platform/analytics-insights/customer-voice#feedback-insights) page has nothing to report on beyond the built-in `message_feedback` capture.</Note>

## Before you begin

Before creating or managing feedback templates, confirm the following.

* **Project access.** You must be signed in to Studio and have access to the project where you want the survey.
* **Agent access.** To collect responses from a conversation, you need an agent you can edit and a project you can deploy.
* **API key (optional).** To submit responses from an external system, you need a project API key with the feedback scopes. See [Collect responses from an external system](#collect-responses-from-an-external-system).

## Access the Feedback Templates page

1. Open the project you want to work in.
2. In the project sidebar, under **Resources**, select **Feedback Templates**.

The page lists every template in the project. Use the search bar to filter the list by name, and select a template to open it.

If the project has no templates yet, the page shows an empty state with a **Create Template** option.

## Create a template

Studio creates templates through a three-step wizard: Basic Info, Configuration, and Review.

**To create a template:**

1. On the Feedback Templates page, select **Create Template**.
2. Complete each step of the wizard as described below.
3. On the **Review** step, select **Create Template**.

### Step 1: Enter basic information

Enter the survey details, then choose the survey type and the voice call behavior.

| Field           | Required | Description                                                                                                                                          |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**        | Yes      | The name agents use to reference the survey. Studio references it verbatim in the agent's `FEEDBACK` block, so it must be unique within the project. |
| **Description** | No       | A short summary of what the survey measures.                                                                                                         |

Select a survey type. The type determines the available fields and the scoring range.

| Survey type      | Rating control           | Use it to                                                 |
| ---------------- | ------------------------ | --------------------------------------------------------- |
| **NPS**          | Scale of 0 to 10         | Measure how likely users are to recommend the experience. |
| **CSAT**         | Five stars               | Measure satisfaction with a specific interaction.         |
| **Like/Dislike** | Thumbs up or thumbs down | Capture a quick positive or negative signal.              |
| **Comment only** | None                     | Collect free text without asking for a rating.            |

<Warning>You can't change the survey type after you create the template, because scores are only comparable within the same type. To ask on a different control, create a new template.</Warning>

Select the voice call behavior. Surveys don't run on voice calls by default, and this setting doesn't affect chat conversations.

| Option           | Behavior on a voice call                |
| ---------------- | --------------------------------------- |
| **Not on voice** | The platform skips the survey entirely. |
| **Keypad**       | The caller responds using keypad input. |
| **Speech**       | The caller responds by speaking.        |

Select **Next**.

### Step 2: Design the survey

The Configuration step controls what end users see. A live preview on the right shows the survey as it renders, with separate **Text** and **Voice** tabs. Select a rating in the preview to see any conditional follow-up or comment box.

Complete the **Survey design** fields.

| Field                   | Required | Description                                                                       |
| ----------------------- | -------- | --------------------------------------------------------------------------------- |
| **Question**            | Yes      | The question end users answer.                                                    |
| **Submit button**       | No       | The button label. Keep it to a few words so it fits the button.                   |
| **Thank-you message**   | No       | The message that replaces the survey once an answer is sent. Keep it to one line. |
| **Lowest value label**  | No       | The label at the low end of the rating scale, for example, Not likely.            |
| **Highest value label** | No       | The label at the high end of the rating scale, for example, Very likely.          |

#### Add a follow-up question

Turn on **Follow-up question** to ask for more context when a rating alone doesn't explain why — for example, after a low score. Follow-up answers are reported separately and never affect the main score.

Add one or more conditions that determine when the follow-up appears.

<Note>The platform asks only one follow-up question. It evaluates conditions from top to bottom, asks the question attached to the first match, and skips the rest. Put your most specific condition first.</Note>

#### Add a comment box

Turn on **Comment box** to collect free text alongside the rating. Set the **Prompt** and the **Placeholder** text end users see.

By default, the comment box appears after every rating. Add conditions to show it selectively.

<Note>The platform checks every comment box condition when a score comes in, and shows the box if any condition matches. Order doesn't matter here.</Note>

Select **Next**.

### Step 3: Review and create

The Review step shows the live preview, the reference snippet, and a **What you are creating** summary of the name, question, rating control, voice behavior, follow-up, and comment box settings.

Review the summary, then select **Create Template**.

<Warning>Saving a template doesn't publish the survey. To start collecting feedback, reference the template from an agent and deploy the project.</Warning>

## Reference a template from an agent

An agent presents a survey when its response includes a `FEEDBACK` block that references the template by name. Copy the snippet from the template's **Usage** tab and paste it into the agent's response block.

### Default rendering

Everything the end user sees comes from the template. The block carries the reference and, optionally, the agent-owned guard.

```yaml theme={null}
RICH_CONTENT:
  FEEDBACK:
    FEEDBACK_TEMPLATE: Testing_feedback   # the reference
```

### Override wording

Override any individual string on the agent side — for example, to supply another language or channel-specific phrasing using the agent's existing locale files. Anything you leave out still comes from the template.

```yaml theme={null}
RICH_CONTENT:
  FEEDBACK:
    FEEDBACK_TEMPLATE: Testing_feedback
    prompt: "¿Qué probabilidad hay de que nos recomiende?"
    submit_label: "Enviar"
    # type, range and the conditions stay with the template
```

The response records which fields the agent overrode, so wording differences stay traceable rather than silent.

<Tip>Use the **Rendered language** segment on the [Feedback Insights](/agent-platform/analytics-insights/customer-voice#feedback-insights) page to compare scores across the languages your overrides produce.</Tip>

## Edit a template

Open a template from the Feedback Templates page and use the **Content** tab to change the survey design, the follow-up question, the comment box, and the voice call behavior. Select **Save** to apply your changes.

The **Rating control** field is locked and displays the control you chose at creation.

<Warning>The rating control is fixed after creation. Changing it would invalidate every score already collected against the survey. To ask on a different control, create a new template.</Warning>

## Track where a template is used

Open a template and select the **Usage** tab. The **Agents using this survey** panel lists every agent that currently triggers the survey. Select **Refresh** to re-check.

If no agent references the template, the panel reports that no agent is linked — the survey isn't collecting feedback from conversations.

## Collect responses from an external system

Use the public feedback API to submit responses from a host app with its own logic, an existing IVR, or a follow-up email. The **External submissions** panel on the **Usage** tab shows the request for the current template.

```json theme={null}
POST /api/public/feedback/projects/<projectId>
x-api-key: <project API key>

{
  "survey": "Testing_feedback",
  "session_id": "sess_01hL_",
  "rating": 10,
  "comment": "optional open text",
  "channel": "email",
  "response_source": "optional, your own capture source",
  "message_id": "optional, your own message/turn id"
}
```

Note the following behavior.

* The platform validates the payload against the template. It rejects a rating outside the template's range rather than clamping it.
* The caller can't supply a score. You choose how the platform reads recorded ratings later, in Insights.
* `session_id` is optional. The platform attributes the response later if the session isn't resolved yet.
* Every response records its source, so external feedback counts toward the same number and stays separable from feedback captured at runtime.

Create the API key under **Settings > API Keys** with the scopes you need.

| Scope                     | Allows                |
| ------------------------- | --------------------- |
| `feedback.surveys.submit` | Submitting responses. |
| `feedback.surveys.read`   | Retrieving responses. |

<Warning>Retrieval returns comment text to any caller that holds the read scope. Issue the read scope only to systems that are allowed to see open text.</Warning>

## Delete a template

Open the template and select **Delete**.

## What's next

After an agent starts collecting responses, analyze them on the [Feedback Insights](/agent-platform/analytics-insights/customer-voice#feedback-insights) page. To review individual ratings and comments captured across the project, see [Customer Voice](/agent-platform/analytics-insights/customer-voice).