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.

Until you create at least one template, the Feedback Insights page has nothing to report on beyond the built-in message_feedback capture.

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.

Access the Feedback Templates page

Open the project you want to work in.
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:

On the Feedback Templates page, select Create Template.
Complete each step of the wizard as described below.
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.

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.

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.

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.

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.

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.

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.

Saving a template doesn’t publish the survey. To start collecting feedback, reference the template from an agent and deploy the project.

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.

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.

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.

Use the Rendered language segment on the Feedback Insights page to compare scores across the languages your overrides produce.

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.

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.

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.

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.

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.

Delete a template

Open the template and select Delete.

What’s next

After an agent starts collecting responses, analyze them on the Feedback Insights page. To review individual ratings and comments captured across the project, see Customer Voice.

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Create and manage feedback templates

What’s a feedback template

Before you begin

Access the Feedback Templates page

Create a template

Step 1: Enter basic information

Step 2: Design the survey

Add a follow-up question

Add a comment box

Step 3: Review and create

Reference a template from an agent

Default rendering

Override wording

Edit a template

Track where a template is used

Collect responses from an external system

Delete a template

What’s next

​What’s a feedback template

​Before you begin

​Access the Feedback Templates page

​Create a template

​Step 1: Enter basic information

​Step 2: Design the survey

​Add a follow-up question

​Add a comment box

​Step 3: Review and create

​Reference a template from an agent

​Default rendering

​Override wording

​Edit a template

​Track where a template is used

​Collect responses from an external system

​Delete a template

​What’s next

What’s a feedback template

Before you begin

Access the Feedback Templates page

Create a template

Step 1: Enter basic information

Step 2: Design the survey

Add a follow-up question

Add a comment box

Step 3: Review and create

Reference a template from an agent

Default rendering

Override wording

Edit a template

Track where a template is used

Collect responses from an external system

Delete a template

What’s next