WhatsApp CSAT survey after conversation close

[mvanhorn]

Proposal

feat(atendimento): WhatsApp CSAT after conversation close

Motivation

Operators running a self-hosted AI sales inbox need a quality signal after a conversation ends. Intercom, Chatwoot, and Kommo all ship post-conversation CSAT. DeskcommCRM’s own PRD lists NPS pós-atendimento as a success metric, and Spec 07 sketches a csat-trigger on resolve/fulfill — but production code never sends a survey.

Today POST /api/v1/conversations/[id]/close flips status via fn_service_status and writes audit conversation.closed. There is no event_log row for automations, no survey table, and no side-effect on the WhatsApp channel. Closing a chat is a silent dead-end for product quality.

This feature was proposed from code analysis without hands-on usage (bulk dogfooding skipped).

Research Summary

General Project Dogfooding

• Installed and ran project: NO (bulk skip)
• Score: 0/10

Feature-Specific Validation

• Feature validated: no (bulk skip)
• Key finding: close route audits only; grep for csat|nps_ under lib/ / app/ (excluding docs) returns no implementation; PRD/spec text is aspirational.

Project Context

• Stars: 1644 | TypeScript / Next.js 16 / Supabase | Maintainer @melgarafael
• Philosophy: AI that operates the CRM; LGPD; self-host truthfulness; measurable gates

Related Issues & Community Signals

• Dup-check CLEAN 2026-09-12 (no CSAT/NPS survey issue or PR)
• Do not confuse with sentiment handoff or opt-out (opt-out: "não me mande mais X" bloqueia quando X não é comunicação (cobrança, fatura, pedido) — nos dois idiomas #435)
• Social: self-hosted AI WhatsApp CRM demand; Chatwoot users discuss message cost and automations — quality loops are table stakes vs SaaS incumbents

Competitive Analysis

• Chatwoot: CSAT survey after resolve
• Intercom: conversation ratings
• Kommo/Octadesk: post-attendance satisfaction in WhatsApp CRM category
• Deskcomm: none

Proposed Solution

Opt-in per organization. When enabled, closing a conversation schedules a one-shot WhatsApp CSAT (1–5) to the contact on the same channel session, after a short delay, only if the 24h session window (or WAHA equivalent) still allows free-form text. Store the rating; never block or fail the close API if the survey path errors.

Behaviour:

1. Setting organizations.settings.csat (zod): { enabled: boolean, pergunta: string, atraso_ms: number, validade_ms: number } with safe defaults (enabled false; Portuguese default question; ~60s delay; ~48h reply window).
2. On close: after successful fn_service_status + audit, insert event_log conversation.closed (so automations can also react) and/or enqueue job csat_survey idempotent on (organization_id, conversation_id).
3. Worker/handler: if enabled and no prior survey row for that conversation, send text via existing sendMessageHandler / ledger path (same blocked-contact and pacing guards). Body like: "De 1 a 5, como foi o atendimento?" — use traduzir / org locale. Mark survey sent.
4. Inbound: early in WAHA/Meta ingest (or a small gate beside follow-up reactivity), if contact has an open CSAT survey awaiting reply and the message is a lone digit 1–5 (or emoji equivalents), record rating, mark answered, do not run the AI turn for that message. Non-matching inbound clears nothing (survey stays open until validity expires).
5. Schema csat_surveys: org, conversation, contact, channel_session, status (pending|sent|answered|expired|skipped), rating nullable, sent_at, answered_at; unique (organization_id, conversation_id); RLS tenant isolation + isolation test list update.
6. UI: Settings › Atendimento — toggle + editable question + “skip if already rated this contact in 7d” optional later (out of scope v1).
7. Metrics (minimal): count answered + average rating on existing metrics page or a single card — only if a clear existing surface exists; otherwise ship storage + setting + send/ingest and leave dashboards for a follow-up.

Out of scope: Meta HSM templates for outside-session, NPS 0–10 variant, public web form, forcing conversations.status='resolved' writers, AI auto-close.

Success: close a conversation with CSAT enabled → contact receives the question on WhatsApp → reply 5 stores rating and does not trigger an AI sales reply.

Approach

Complexity M. Estimated ~250–400 LOC + migration triple.

1. Schema triple

Migration + baseline appendix + MANIFEST. Include RLS policy tenant_isolation_csat_surveys_all and add table to isolation test allowlist.

2. Pure helpers

lib/csat/pesquisa.ts: decide whether to enqueue; render question; parse rating from inbound text. Fully unit-tested (no network).

3. Close wiring

close/route.ts: keep current success path; add best-effort event_log insert + enqueue. Failures log and still return ok(conv).

4. Handler

Register in ensureHandlersRegistered. Skip when disabled, already surveyed, contact blocked, or channel cannot send.

5. Ingest short-circuit

Before ai_agent.dispatch_requested / inbound-turn, consume rating replies.

6. Settings API + form

Admin-only PATCH; merge jsonb settings (do not clobber unrelated keys — follow ai/providers merge pattern).

7. i18n + changelog fragment

.changes/csat-pos-fechamento.md for release screen; strings via traduzir / useT.

8. Tests

• Unit: parse rating; idempotent enqueue; disabled skip
• Handler: mock send; blocked contact
• Optional invariant: RLS on new table
• Do not require full Playwright WAHA for merge; describe manual proof for maintainers

PR strategy

• Title: feat(atendimento): pesquisa CSAT no WhatsApp ao fechar a conversa
• Body: user-facing Portuguese summary; AI disclosure per AGENTS.md; link discussion if orchestrator filed one
• Proposal lane: Ideas discussion first (process gate); PR only if/when maintainers accept

---

Happy to open a PR if this direction works for you.

AI was used for assistance.

[deskcomm-bot]

Thanks for the detailed proposal, @mvanhorn. I checked it against today's main and the diagnosis holds:

• Closing a conversation (app/api/v1/conversations/[id]/close/route.ts, lines 158-177) only flips the status through fn_service_status and writes the conversation.closed audit entry. Nothing goes to event_log, so automations can't react to a close either.
• There is no CSAT/NPS survey anywhere in app/, lib/, components/ or the migrations.

I opened #4023 with this, split into a small step (emit conversation.closed to event_log, which already lets an automation send a follow-up message) and the full survey, which is marked as a product decision. Scope and go-ahead belong to the maintainers there, so please wait for their call on #4023 before opening the PR. When you do, CONTRIBUTING.md and the deskcomm-contribuir guide check the migration triple and the release fragment before triage does.

— Assistente de IA do DeskcommCRM. Para falar com uma pessoa do time, mencione @melgarafael.