> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings: CSAT console walkthrough

> Configure the Auto-CSAT survey surface at /settings/csat — pick a template, set dispatch timing and trigger scope, tune the detractor thresholds, and read the score.

# Settings: CSAT console

The **CSAT** console in Orbit (`/settings/csat`) is the tenant-owned survey-configuration surface listed on the Settings hub as:

> CSAT | `/settings/csat` | Customer satisfaction survey configuration and scoring

From it you control the auto-survey loop end to end: which survey template fires when a conversation closes, how long the dispatch waits, which conversations qualify, and where the 1–5 score groups your customers. Everything on this page is configurable by your organization — no platform-side compliance guard sits over survey dispatch.

<Note>The console is owner/admin only. Operators see the answers it produces, not the configuration itself.</Note>

***

## 1. What the CSAT console owns

One page manages four distinct surfaces:

* **Survey template and timing.** Which CSAT / NPS / CES template fires on conversation close, and the dispatch delay (1 minute to 24 hours) between resolve and send.
* **Trigger scope.** A smart-sentiment gate, a per-contact fatigue cooldown, and an optional condition editor that narrows dispatch by channel, assigned agent, and closing disposition.
* **Scoring policy.** The CSAT (1–5) and NPS (0–10) detractor bands, and whether a detractor answer auto-reopens the conversation.
* **Channel eligibility.** The condition editor's channel chips gate which channels auto-dispatch fires on; all dispatch still flows through the same opt-out-checked sender every manual survey uses.

All fields persist into the organization settings block (`GET/PUT /api/v1/settings/general`), and every change is captured by your audit log.

***

## 2. Field-by-field walkthrough

Open **Settings → CSAT**. Each card below maps to one control on the page.

### Master toggle — Enable auto-survey

* **What it does**: when on, every conversation that transitions to `closed` schedules a survey dispatch.
* **Default**: on for new tenants.
* **Toggle it off** to pause auto-surveys tenant-wide without losing your template or timing configuration. Manual survey sends from the API still work.

### Survey template

* **What it does**: picks which template fires. The picker enumerates every row in your survey library whose type is `csat`, `nps`, or `ces`.
* **Create templates** under **Insights → Surveys**; the page links straight through when the list is empty.
* **Edge case**: if no template is selected, conversations close normally but no survey is sent — the close-arming hook reads an empty template id as "not armed." Select a template before turning the toggle on.

### Dispatch delay after resolve

* **What it does**: the minutes to wait between `closed` and the send. The slider is single-thumb (minutes) with a live read-out (`5 min`, `1h 30m`, `24h`).
* **Clamped to 1–1440** (1 minute → 24 hours) on both save and normalisation.
* **Typical**: 5–30 minutes for transactional support. Longer delays reduce reply rates but feel less intrusive.

### Smart CSAT triggering

* **What it does**: when on, the dispatcher skips two classes of closes before sending — conversations the sentiment pipeline labelled negative, and contacts inside your cooldown window. Off fires on every eligible close regardless of sentiment.
* **Default on.** Skip a negative-sentiment close on purpose: surveying a customer who just had a bad experience tends to inflame rather than collect signal.

### Per-contact cooldown

* **What it does**: minimum days between surveys for the same contact, across *all* templates and *both* the CSAT and NPS tracks.
* **Clamped to 7–90 days.** Default 14.
* The cooldown counts any `survey_responses` row for the contact, so a contact who answered a survey yesterday cannot receive another today.

### Conditional triggers

The condition editor narrows which closes fire. Leave it empty and every eligible close is surveyed. Add one or more condition cards; a conversation is surveyed when it matches **any** card, and within a card every selected filter must match:

* **Channels** — chip toggles for the conversation channel (SMS, WhatsApp, email, voice, etc.). An empty selection means any channel.
* **Assigned agents** — restrict dispatch to closes resolved by specific team members. A conversation never assigned to a human (bot-only) never matches a non-empty agent list.
* **Dispositions** — restrict to closes stamped with specific inbox disposition labels. An empty list means any disposition.
* **Exclude bot-only conversations** — a per-card switch that skips conversations never picked up by a human agent.

Empty cards and cards with no filters selected are stripped on save, so the persisted configuration stays minimal.

### Detractor rescue

Two thresholds classify an incoming rating, plus an optional auto-reopen playbook:

* **CSAT detractor threshold** — on the 1–5 scale, ratings at or below this value are detractors. Default 2; clamped to 1–4.
* **NPS detractor threshold** — on the 0–10 scale, ratings at or below this value are detractors. Default 6 (Bain canonical: 0–6 detractor, 7–8 passive, 9–10 promoter); clamped to 0–9.
* **Reopen conversation on a detractor rating** — when on, a detractor answer flips the conversation back to `open` and tags it `csat_detractor` so an agent can rescue the relationship. When off, the detractor webhook event still fires; the conversation just stays closed. Archived conversations are never reopened.

The API rejects 0 (no detractors possible) and 5 on CSAT (every rating a detractor) as misconfigurations; the slider clamps to the same bounds so what you save round-trips honestly.

### Save

The save bar enables once any field changes. All edits land in a single org-settings write, so a partial save can't leave the console in a mixed state.

***

## 3. How a survey is triggered from a closed conversation

The close path arms and the dispatcher fires — two steps, both driven by this page:

1. **Close arms the dispatch.** When a conversation transitions to `closed`, the close handler reads your console configuration. If the master toggle is on, a template is selected, and — if the condition editor is in use — the conversation matches at least one card, the handler stamps a due timestamp (now + your delay) and the template id onto the conversation.
2. **The dispatch sweep fires.** A scheduled sweep scans for stamped conversations whose due time has passed, re-checks smart triggering and the per-contact cooldown at send time, and dispatches through the same sender a manual survey uses — so opt-out, quiet hours, and billing behave identically to a hand-sent survey.

Post-call IVR surveys (digit capture inside a voice call) are a *separate* surface — see [Post-call surveys](/guides/post-call-surveys). This console covers the messaging-channel dispatch only.

***

## 4. Scoring model

* **Scale.** CSAT answers use integers 1–5 (NPS sibling: 0–10). Answers outside 1–5 are rejected at intake.
* **Per-response bucket.** Every response is bucketed at intake as `satisfied` (4–5), `neutral` (3), or `dissatisfied` (1–2). The bucket travels on the response row and on the webhook payload.
* **Aggregate.** The answer rolls into Insights → Surveys and Insights → Sentiment rollups, and into `GET /api/v1/surveys/scorecards` — rows bucketed by `group_by=queue` or `group_by=agent` reporting response count, **top-2-box** satisfaction percent (the share of answers scoring 4–5), average score, and the NPS over NPS rows. A bucket appears only once it has at least one answered response, so unsampled sends never surface as zero-divide rows.
* **Detractor handling.** When a rating lands at or below your CSAT detractor threshold, it is classified detractor at intake — driving the auto-reopen playbook and the anomaly surface's detractor-share signal.

***

## 5. Webhooks and API

### Webhooks

The survey-response webhook emits at most once per response, only after the response row is persisted:

| Event | Fires |
| - | - |
| `survey.csat.response_recorded` | Every CSAT answer — first capture only; a repeat tap on the signed link is idempotent |

```json theme={null}
{
  "event_type": "survey.csat.response_recorded",
  "survey_id": "8f1c0d2e-...",
  "response_id": "3c9ba5f1-...",
  "score": 2,
  "satisfaction_bucket": "dissatisfied",
  "channel": "ivr_voice",
  "agent_user_id": "7d4b1e2c-...",
  "contact_id": "c_9f3e2a1b",
  "responded_at": "2026-10-09T14:02:11Z"
}
```

A detractor answer additionally fires `conversation.csat_detractor` when the rating came in against a conversation — subscribe to that event to open a follow-up case in your CRM within seconds of the response.

### API

| Endpoint | Purpose |
| - | - |
| `GET /api/v1/settings/general` | Read the current CSAT configuration |
| `PUT /api/v1/settings/general` | Persist a change |
| `GET /api/v1/surveys` | List the templates the picker offers |
| `GET /api/v1/surveys/scorecards` | Read the per-queue / per-agent rollups |

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=csat&from=2026-10-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"
```

***

## 6. Limits and edge cases

* **Delay bounds.** 1 minute to 24 hours (1–1440 minutes). Out-of-range values are clamped at save.
* **Cooldown bounds.** 7–90 days. Default 14.
* **Destructive thresholds rejected.** CSAT detractor threshold 0 (no detractors possible) and 5 (every rating a detractor) are rejected by the API; NPS threshold 10 is likewise rejected.
* **Channel eligibility.** A channel chip unselected in every condition card simply never fires on that channel — you scope out channels rather than blacklist them.
* **Suppression and opt-out.** Auto-dispatch flows through the same sender a manual survey uses, so an opted-out contact on a suppression list is skipped at send time — the same tenant-owned guard that gates campaign sends.
* **Cooldown spans templates.** The fatigue window counts `survey_responses` rows across CSAT *and* NPS, so the two tracks cannot jointly over-survey a contact.
* **No template selected.** Closes arm nothing and no survey fires; picking a template later does not retro-dispatch to already-closed conversations.

***

## 7. Troubleshooting

**No survey leaves even though the toggle is on.**
The most common cause is an empty template picker — the close arm hook skips silently when no template is selected. Open the card and select one. (Create a template under **Insights → Surveys** first if the list is empty.)

**No responses are collected.**
A send fired but no score landed. Verify you are not in the per-contact cooldown (a contact inside the 7–90-day window is skipped at send time), check the template's channel — an email survey answered over SMS never links back to the response row — and confirm the contact has not opted out since the last send.

**Score drifts downward over time.**
Check whether smart triggering was recently turned off: firing on every close, including negative-sentiment closes, floods the score with unhappy customers and masks a real trend. Also check the **conditional triggers** editor — a saved card that narrowed scope (e.g. one channel removed) changes the sample mix immediately and the score re-bases.

**Detractor reopens fire on too many or too few answers.**
Re-set the CSAT detractor threshold — a threshold of 4 means ratings of 1–4 all reopen; the default 2 catches only 1–2. The slider clamps to 1–4 on CSAT and 0–9 on NPS; values outside those bounds never persist.

**The dashboard shows a blank page or a load error.**
The organization settings fetch failed — the API or database was unreachable. Use the in-page **Retry** button; the page never writes a partial save.

***

## Related guides

* [CSAT and NPS settings consoles](/guides/settings-liveops-csat-nps) — the joint CSAT/NPS read-path guide
* [Auto-CSAT/NPS dispatch](/guides/auto-csat-nps) — the close-path dispatch loop in detail
* [Surveys end to end](/guides/surveys-voc) — manual, audience-targeted distribution over the API
* [Post-call surveys](/guides/post-call-surveys) — IVR digit capture inside a voice call
* [Settings hub](/settings/overview) — the full console map


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.