AI natural-language customer filter

CRM · AI natural-language customer filter

A prompt box that turns a plain-language audience description into structured customer filters, which are then prepended to whatever filters are already applied.

Area	CRM
Routes	crm.users.index · crm.segments.new
Centre modules	ai
Staff levels	as per customer list / segment builder
Models	user
UI label	ai.error
Coverage	2 use cases · 1 happy · 5 failure

Known issues (2)

• 🟠 Medium — AI filter prompt is not URL-encoded
• 🟠 Medium — AI filter sends prompt text to Sentry

How it works

Only available when auth.center.hasAIUserFilter. The prompt is sent as a query parameter to /api/v4/client_filter, and the JSON returned is reshaped into Filter objects, each resolved to a group filter through userFilters → groupFilterCode → groupFilters. If any filter cannot be matched to a group, the code throws and reports to Sentry. Privacy-conscious by design: the analytics events (AI_FILTER_REQUESTED, AI_FILTER_SUCCEEDED, AI_FILTER_FAILED) deliberately send only the prompt length, filter count and filter types — never the prompt text, because it may contain customer data. Note the prompt is interpolated into the URL without encodeURIComponent, so prompts containing & or # will be truncated.

Use cases

Why someone opens this (2)

• A marketer describing an audience in words instead of assembling six filter rows by hand.
• Quickly exploring a population before saving the result as a segment.

Path map

flowchart LR
    F(["AI natural-language customer filter"]):::feat
    F --> H1["Prompt converted to filters"]:::ok
    F -.-> X1["Empty prompt"]:::bad
    F -.-> X2["No usable filter returned"]:::bad
    F -.-> X3["Unmappable filter key"]:::bad
    F -.-> X4["Network failure"]:::bad
    F -.-> X5["Prompt containing URL-special characters"]:::bad
    classDef feat fill:#157068,stroke:#157068,color:#ffffff,font-weight:bold
    classDef ok fill:#e3f1ea,stroke:#0d6b42,color:#0d4a2e
    classDef bad fill:#f7e6e2,stroke:#9a2d1c,color:#6e1f13

Happy paths

Prompt converted to filters

1. User types e.g. ‘women between 25 and 34 with a valid email in Madrid’.
2. _fetchClientFilter calls the API and parses the returned filter JSON.
3. Each entry is mapped to a Filter with its group, operation and values.
4. onApplyFilter prepends them to the existing filters and AI_FILTER_SUCCEEDED is tracked.

Failure paths

Empty prompt

Cause — Nothing typed.

What happens — isDisabled keeps the apply button inactive.

No usable filter returned

Cause — API responds non-OK.

What happens — error is set and {} returned; the UI shows ai.error (‘No valid filter found’).

Unmappable filter key

Cause — A returned filter key has no matching entry in enums/user-filters, so its group filter is undefined.

What happens — getFilters throws, reports GPT filter error to Sentry with the prompt and filter payload, sets error and returns []. Note this Sentry capture does include the prompt text, which is at odds with the deliberate no-prompt policy in the analytics calls.

Network failure

Cause — Fetch rejects.

What happens — AI_FILTER_FAILED is tracked with reason: 'network' and the error is re-thrown, so isLoading is left true and the spinner sticks.

Prompt containing URL-special characters

Cause — Prompt is concatenated into the query string unescaped.

What happens — Not handled — the prompt is silently truncated at &/#, producing a confusingly wrong filter.

QA checklist

Tick these off while regression-testing this feature. The boxes are plain Markdown, so progress is visible in git diffs.

• ✅ Prompt converted to filters
• ⛔ Empty prompt
• ⛔ No usable filter returned
• ⛔ Unmappable filter key
• ⛔ Network failure
• ⛔ Prompt containing URL-special characters

Implementation

• app/components/nf-ai-filter.js
• app/models/module-ai.js
• app/utils/filter.js

Translation keys (2)

Key	English
ai.error	No valid filter found
modules-ai	ArtificiaI Intelligence

Related

• Same area — Customer list & filtering · Customer create & edit · Customer deletion with unsubscribe notice · Customer CSV export with column picker · Customer CSV import · Children CSV import · Save current filters as a segment · Segment list, refresh & export · Segment builder with automatic tag actions · Segment categories · User tags (user types) · Customer receipts tab & ticket-stamp generation · Customer loyalty — raffle tickets · Customer loyalty — cards & stamps · Customer loyalty — rewards · Customer loyalty — coupon exchanges · Customer children (dependants) · Receipt verification queue · Store list, filters & exports · Store create & edit · Store CSV import · Store labels (store types) · Customer action log (dormant)
• Shares data with — Data-quality dashboard · Play centre stays (check-in - check-out) · Realtime updates (Pusher)
• Behind the same module — Proposal editor (content, coupon, push, AI images) · Segment builder with automatic tag actions · CandelarIA smart assistant

---

Generated from doc/feature-inventory.json · id crm-ai-filter · commit 276788ca6