> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Surveys
> Measure customer satisfaction with in-call voice CSAT surveys.
Use CSAT surveys to measure whether callers are satisfied with how the agent handled their request. Without direct feedback data, you are relying on proxy metrics (containment, duration) that do not tell you how the caller actually felt.
CSAT surveys collect feedback from customers at the end of their conversation. The agent asks customers to rate their experience on a 1–5 scale, and responses are tracked in your analytics dashboards and exported data.
PolyAI currently supports voice CSAT surveys – in-call surveys where the agent asks customers to rate their experience before ending the conversation.
## Configuring voice CSAT
Voice CSAT is configured from **Configure > CSAT** in the sidebar.
### Step 1: Enable the survey
At the top of the CSAT settings page, toggle **Enable in-call voice survey** to on. This activates the CSAT feature for your project. Until enabled, no surveys run.
### Step 2: Connect to your end function
Add `conv.goto_csat_flow()` to your end function in **Build > Tools**. This instructs the agent to route users into the survey flow before ending the conversation.
Here is the complete function definition:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def goodbye_and_hang_up(conv: Conversation):
conv.goto_csat_flow()
```
This step is required. If you skip it, the survey never triggers – even if the toggle is on. The function should end with `conv.goto_csat_flow()` and not return anything.
If you want a custom final message before the survey, set the utterance in `conv.state.csat_output_args` before calling `conv.goto_csat_flow()`:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def goodbye_and_hang_up(conv: Conversation):
conv.state.csat_output_args = {"utterance": "Custom final thank you message"}
conv.goto_csat_flow()
```
Without this, the agent uses the default lead-in message configured in your CSAT settings.
### Step 3: Define survey content
Configure the two text fields in the **Content** section:
What the agent says before asking the question. Keep it short and clear to prevent hang-ups.
**Example:** "Please stay on the line to answer a quick survey about your experience."
The actual rating question. You must include a 1–5 scale in the wording – the system does not infer a scale.
**Example:** "On a scale of 1 to 5, how well was your issue resolved today?"
Once configured, every time your end function executes, the user routes into the CSAT flow before the conversation ends.
## How CSAT works
1. **Customer completes conversation** - The agent finishes helping the customer
2. **Lead-in message** - Agent introduces the survey
3. **Survey question** - Agent asks the 1–5 rating question
4. **Customer responds** - Customer provides a rating
5. **Data collection** - Rating is stored and appears in your dashboards
## CSAT best practices
**Tips for effective surveys:**
* **Keep it short** - Customers are more likely to respond to brief surveys
* **Be clear about the scale** - Explicitly state what 1 and 5 mean in your survey question
* **Natural language** - Write messages that sound conversational, not robotic
* **Test thoroughly** - Try different phrasings in sandbox before deploying
## Viewing CSAT data
### Agent Studio dashboards
CSAT scores appear in your analytics dashboards within Agent Studio:
1. Navigate to **Configure > Dashboards**
2. Select the **CSAT** dashboard
3. View metrics including:
* Average CSAT score
* Score distribution (1-5)
* CSAT trends over time
* Response rate
* CSAT correlation with containment and resolution rates
### Conversation-level data
Individual CSAT scores are also visible in conversation records:
1. Go to **Analytics > Conversations > Voice**
2. Filter the conversations table to show only conversations with CSAT responses
3. Select a conversation
4. View CSAT metrics in the conversation details
### Conversations API
CSAT scores are included as structured fields in [Conversations API](/api-reference/conversations) responses. You can export this data for:
* Integration with your existing analytics or reporting tools
* Building custom dashboards
* Ingesting into client systems
### Smart Analyst
You can query CSAT data using Smart Analyst for custom analysis and reporting. Smart Analyst provides access to all CSAT metrics and can generate custom reports.
### Tracked metrics
The following metrics are automatically tracked for CSAT surveys:
#### Voice CSAT metrics
* `CSAT_OFFERED` - Whether the survey was offered (boolean)
* `CSAT_ACCEPTED` - Whether the customer accepted the survey (boolean)
* `CSAT_DENIED` - Whether the customer declined the survey (boolean)
* `CSAT_SCORE` - Customer rating (numeric 1-5)
* `CSAT_FREE_FEEDBACK` - Verbatim customer feedback (string, if collected)
* `CSAT_COMPLETED` - Whether the survey was completed (boolean)
These metrics are attached to the original conversation record and can be used for analysis and reporting.
## Rating scale
The standard CSAT scale is 1-5:
| Rating | Interpretation |
| ------ | ----------------- |
| 5 | Very satisfied |
| 4 | Satisfied |
| 3 | Neutral |
| 2 | Dissatisfied |
| 1 | Very dissatisfied |
### CSAT calculation methods
CSAT scores can be calculated in different ways depending on your reporting needs:
**Standard average**
Simple average of all CSAT scores (e.g., 4.06 out of 5.0). This is what PolyAI dashboards report by default.
**Net Promoter style (client-side)**
Some organizations apply a Net Promoter Score-style calculation to their exported CSAT data. This is not calculated by PolyAI – you would apply it to your own data exports:
* CSAT Score = (Promoters - Detractors) / Total responses
* Promoters: Scores of 4-5
* Detractors: Scores of 1-2
* Neutral: Score of 3 (not included in calculation)
Example: If 70% of customers rate 4-5 and 10% rate 1-2, the CSAT score would be 60%.
## Troubleshooting
* Check that `conv.goto_csat_flow()` is called in your end function
* Ensure the end function is being executed (check conversation logs)
* Simplify your survey messages
* Make the scale clearer (explicitly state what 1 and 5 mean)
* Consider the timing - surveys work best after successful resolutions
* Allow up to 15 minutes for data to appear
* Verify the conversation completed successfully
* Check that the customer actually provided a rating
## Limitations
* The rating scale is fixed at 1-5
* Only one CSAT survey can be triggered per conversation
* Survey must be triggered from the end function
For custom survey requirements or multi-question surveys, contact your PolyAI representative to discuss advanced options.
## Related pages
Add conv.goto\_csat\_flow() to trigger surveys at conversation end.
View CSAT scores alongside containment and other key metrics.
Query CSAT data and surface satisfaction trends.