Sentiment Analysis — Setup & Usage Guide

Overview

The Sentiment Analysis module is an AI-powered sentiment scoring system built into Rubi Professional CRM. Once activated, every customer interaction logged by an agent — call notes, chat transcripts, email summaries, omnichannel messages — is automatically scored by Anthropic's Claude for sentiment, dominant emotion, and confidence.

The module turns noisy interaction logs into three high-value signals: a customer-level risk indicator, an agent performance view, and real-time alerts when things are going sideways.

How it works

The module consists of three moving parts:

1. A scorer (SentimentAnalyzer class) that sends each interaction's text to Claude, parses the response as structured JSON, and stores the result in interaction_sentiment with the score, label, dominant emotion, confidence, and keywords that drove the verdict.
2. A hook inside /crm/api/log-interaction.php that calls the scorer after a successful interaction save. The hook is wrapped in try/catch — if the Claude API is down, your interaction logging still works normally.
3. A set of views (v_customer_sentiment_rollup, v_agent_sentiment_rollup) that pre-aggregate scores for fast dashboard rendering, plus a daily rollup table that powers the 30-day trend chart.

Each scored row carries:

• Score — integer from −100 (angriest) to +100 (happiest)
• Label — positive, neutral, negative, or mixed
• Confidence — how sure the model is, 0-100%
• Dominant emotion — a single word (frustration, relief, gratitude, etc.)
• Summary — one or two analyst-voiced sentences describing what happened
• Keywords — the specific phrases that drove the score

Quick start ≈ 5 minutes

Configuration settings

All settings live at /tenant-admin/modules/sentiment-settings.php and persist to the tenant_modules.settings.sentiment_analysis JSON key. Changes take effect on the next interaction scored.

General

• Enable sentiment scoring — master switch. When off, no new interactions are scored even if the module itself is active.
• Channels to score — opt individual channels in/out. Available: web, chat, email, voice, sms, phone. Default: all.
• Claude model — optional override. Leave on "Tenant default" unless you know you need a specific model for quality or cost tradeoffs.

Negative-sentiment alerts

• Alert threshold — integer between −100 and +100. An alert fires when score ≤ this number. Default −50.
• Cooldown (minutes) — don't re-alert for the same customer within this window. Default 30.
• Who gets the alert — choose Tenant admins & supervisors, Supervisors / managers only, or Specific users. The specific-users picker shows when the third option is selected.

Text & Budget

• Minimum note length — skip scoring on notes shorter than this (default 20 chars). Prevents wasting tokens on "Called customer." stubs.
• Maximum note length — truncate notes longer than this before sending to Claude (default 8000 chars). Keeps token costs bounded per call.
• Daily token cap — hard limit per day. 0 = unlimited. Default 100,000 tokens (~$0.30/day at Sonnet pricing).

Advanced

• Emit Workflow Engine events — fires sentiment.scored + sentiment.negative on every applicable score. See Workflow & webhook events.
• Dispatch outbound webhooks — subscribed webhook endpoints receive the same events. Configure endpoints under Tenant Admin → Webhooks.

Understanding the dashboard

The tenant-admin dashboard at /tenant-admin/modules/sentiment-analysis-dashboard.php surfaces the most actionable signals:

Headline stats

Four at-a-glance cards: Total scored, Average sentiment, Positive count, Negative count. Today's numbers are called out underneath.

Sentiment trend (last 30 days)

Line chart of daily average score. Quick way to spot weeks where morale or product experience shifted. Hover a point to see how many interactions were scored that day.

Label mix

Donut showing what percentage of your scored interactions are positive, neutral, negative, or mixed — across all time.

At-risk customers

Customers whose average sentiment is ≤ 0 across 2 or more scored interactions. Lowest first. This is where to spend outreach and retention energy.

Top agents & coaching opportunities

Two side-by-side panels. Top agents ranks your highest-average-sentiment agents (min 3 scored interactions) — good candidates for mentoring roles. Coaching opportunities flips the list: your lowest-average agents, where short 1:1 coaching sessions will have the biggest impact.

Today's activity

Live counter of interactions scored today, alongside a progress bar showing how much of your daily token budget has been used. The bar turns yellow at 65% and red at 85%.

Alerts & notifications

When a score drops to or below your alert threshold, the module dispatches an in-app notification and queues an email (respecting each recipient's per-category notification preferences). The alert links directly to the customer's profile so the supervisor can click through and intervene.

Cooldown: to prevent alert fatigue, the module won't fire another alert for the same customer within your configured window (default 30 minutes). Even if the customer has three negative interactions in that window, only one alert goes out.

Who hears the alert: by default, all active users in your tenant with the admin, tenant_admin, supervisor, or manager role receive it. You can narrow this to supervisors only, or pick a specific list of users if you have dedicated retention staff.

Manual overrides

The AI is good but not perfect. Sarcasm, cultural context, and industry jargon can all produce misleading scores. Any user with access to the customer profile can override an AI score using 👍 / 👎 controls on the interaction timeline.

Overrides are stored in the same interaction_sentiment row alongside the AI's original score, in the human_override_* columns. The rollup views use COALESCE(human_override_*, *), meaning corrections take precedence over the AI verdict in every aggregate.

Every override is written to audit_log with action sentiment_override, capturing who reviewed, when, and what changed. No data is ever lost.

Backfilling historical data

Fresh activations see an empty dashboard until new interactions start flowing in. The backfill utility at /admin/backfill-sentiment.php fixes that.

Unscored mode (safe)

Picks the N most recent interactions that don't have a sentiment row yet. Idempotent — running it twice won't re-spend tokens on anything already scored. Start here.

Refresh mode (use carefully)

Re-scores the N most recently created interactions with force-refresh. Every call costs tokens. Use this after a prompt or model change, or when you want to verify the scorer is behaving consistently on known data.

Controls

• Batch size — 1 to 100 interactions per run.
• Sleep between calls — rate-limit pause in ms. Default 200 ms. Use higher values if you're hitting API rate limits.
• Confirm checkbox — required. Acknowledges that you're spending tokens.

Workflow & webhook events

The module emits two event types on every scored interaction:

Both events can drive Workflow Engine rules ("when sentiment.negative fires, assign the customer to the retention queue") and can be dispatched to outbound webhook endpoints (Slack, Zendesk, PagerDuty, or any custom webhook).

Cost & budget controls

Sentiment Analysis has two cost components: the $99.99/mo module subscription and the Claude API tokens consumed on each scoring call. A typical interaction costs roughly 500-700 tokens end-to-end (prompt + response), which at Claude Sonnet pricing is a fraction of a cent per score.

Three controls keep your spend bounded:

• Daily token cap — hard-stops scoring for the day when exceeded. Default 100,000 tokens ≈ $0.30 at Sonnet pricing.
• Minimum note length — skips trivial notes so you don't spend tokens on "Called." entries.
• Maximum note length — truncates very long notes before sending so a single call can't run away.

Today's token usage is visible on the dashboard as a progress bar. Tenant Admin → AI Usage has month-over-month totals across all AI features (AI Coach, Customer Intelligence, Sentiment Analysis, RubiLens).

Developer API reference

Two internal HTTP endpoints expose sentiment data to the CRM UI. Both require a logged-in session.

GET /crm/api/sentiment.php?action=customer_rollup&customer_id=123

Returns aggregate sentiment stats for a single customer plus the last-scored label/score. Used by the customer profile sidebar.

{
  "ok": true,
  "rollup": {
    "total_scored": 7,
    "avg_score": 42.1,
    "count_positive": 5,
    "count_negative": 1,
    "count_neutral":  1,
    "count_mixed":    0,
    "first_scored_at": "2026-03-02 10:14:00",
    "last_scored_at":  "2026-04-22 18:33:11"
  },
  "last": { "score": 85, "label": "positive", "created_at": "2026-04-22 18:33:11" }
}

GET /crm/api/sentiment.php?action=escalation_queue&hours=24

Returns recent negative-labeled interactions needing attention, lowest score first. Used by the escalation queue.

POST /crm/api/sentiment.php?action=set_override

Writes a human override on an AI score. CSRF-protected. Body: { sentiment_id, score?, label? }.

Tenant-admin settings API

/tenant-admin/api/sentiment-settings.php exposes get, save, and reset actions. All writes are CSRF-protected and whitelist the accepted keys.

Troubleshooting

Frequently asked questions