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 comparable results.

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.

The Feedback Insights page displays reports only after you create at least one template.

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 required project, and in the sidebar, select Resources > 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.

Create a template

Create a template using Studio’s three-step wizard:

1. On the Feedback Templates page, click Create Template.
2. Complete basic info, configuration, and review steps below.
3. On the Review step, click 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.

Click 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.

Click 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 click 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 in the ABL editor.

Where you place the block depends on how the agent is built. A flow-based agent attaches the survey to a specific step. A reasoning agent has no fixed step to attach to, so it attaches the survey to a COMPLETE branch. Both forms use the same FEEDBACK block.

The FEEDBACK_TEMPLATE value must match the template Name verbatim. If the names don’t match, the survey doesn’t render. After you add the block, deploy the project to start collecting responses.

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

Add a survey to a flow-based agent

In a flow-based agent, add the FEEDBACK block to the step where you want to ask for feedback. The following agent greets the caller, moves to a dedicated ask_feedback step, and presents the survey there.

AGENT: midflow_survey_test
GOAL: "Verify a survey on a mid-flow step"
PERSONA: "Calm and brief"

FLOW:
  entry_point: greet
  steps:
    - greet
    - ask_feedback

greet:
  REASONING: false
  RESPOND: "Hello, this is a survey test call. Please say anything to continue."
  ON_INPUT:
    - ELSE:
      THEN: ask_feedback

ask_feedback:
  REASONING: false
  RESPOND: "Feel free to let us know how you feel"
  RICH_CONTENT:
    FEEDBACK:
      FEEDBACK_TEMPLATE: test_npse

  THEN: COMPLETE

Note the following about this example.

• The step’s RESPOND text introduces the survey. The RICH_CONTENT block renders the survey itself below that message.
• THEN: COMPLETE ends the conversation once the step runs, so the survey is the last thing the end user sees.
• Placing the survey on its own step keeps the ask separate from the work the agent was doing. You can attach the block to any step instead, including one in the middle of a flow.

Add a survey to a reasoning agent

A reasoning agent decides its own path, so there’s no fixed step to attach the survey to. Add the FEEDBACK block to a COMPLETE branch instead, and let the branch conditions decide when the agent asks.

FLOW:
  steps:
    - execute_confirmed_action

  execute_confirmed_action:
    REASONING: true
    available_tools:
      - create_replacement
      - issue_refund
      - apply_goodwill_credit
    instruction: |
      Validate the action request first.
      Execute only the requested confirmed action.
      # instruction trimmed for brevity
    THEN: COMPLETE

COMPLETE:
  - WHEN: status IS SET AND actions IS SET AND follow_up IS SET
    RESPOND: ""
    RICH_CONTENT:
      FEEDBACK:
        FEEDBACK_TEMPLATE: Post_Chat_LikeDislike   # the reference
  - WHEN: failures IS SET
    RESPOND: ""

Note the following about this example.

• The agent evaluates COMPLETE branches in order and runs the first branch whose WHEN condition matches.
• The first branch represents a successful outcome, so the survey attaches there. The agent asks for feedback only when it completed the work.
• The failure branch carries no FEEDBACK block, so the agent doesn’t ask for a rating on an interaction that failed.
• RESPOND: "" leaves the response text empty, so the survey is the only thing the branch renders. The agent has already said what it needed to say during the reasoning step.

Attach the survey to outcome branches rather than to the reasoning step itself. A reasoning step can run several times in one conversation, and each pass through a FEEDBACK block presents the survey again.

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. Click Save to apply your changes.

The Rating control field shows the control you chose at creation; you can’t change it here.

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. Click 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.