Agent Recommended Actions SOP

Standard Operating Procedure — Agent Pulse feature documentation for support, QA, and engineering handoff.

Purpose

This SOP documents the Recommended Actions feature in LiveChat. It covers:

what the feature does for agents and admins
what signals the feature uses
how the frontend and Supabase RPC work together
how to deploy, verify, and troubleshoot it

This feature is intentionally implemented without a new backend service.

Frontend UI
   |
   +--> calls Supabase RPC directly when available
   |
   +--> falls back to client-side ranking if RPC is unavailable
   |
   +--> renders only the highest-signal actions for the current agent

Feature Summary

Recommended Actions is a next-best-action widget for agents. It helps an agent decide:

who to reply to now
which stalled contacts should be re-engaged
which contacts recently clicked a link and are showing intent
which contacts look high-intent based on message volume, lead score, and email engagement

The widget is shown in the LiveChat agent metrics/dashboard card. Current recommendation buckets:

Respond Now
Re-Engage
Clicked Link
High Intent

Only non-empty buckets are shown.

Client-Facing Behavior

What Agents See

Agents see a Recommended Actions card containing one or more sections. Each recommendation row includes:

contact name
optional lead status badge
short reason text
action badge such as Reply now, Act on click, Follow up, or Focus
a small context line (message counts, click counts, or time since last activity)
a Send to To Do button

What Each Bucket Means

Respond Now

The contact is waiting on the agent. The most recent message is inbound and the agent has not replied. Sorted by unread count and wait time — your #1 priority.

Re-Engage

The conversation is going silent. The agent sent the last message (24h–7d ago) but the contact hasn't replied. A well-timed follow-up can revive the chat.

Clicked Link

The contact recently clicked a tracked SMS or email link. This is often the strongest short-term buying signal after a direct reply.

High Intent

Strong engagement patterns — high message volume, lead score, or email opens — without falling into other buckets. Highly likely to convert.

Signals Used

Core Assignment Scope

Only contacts actively assigned to the current agent are considered. Source: livechat_contact_assignments_with_details

Conversation Signals

last inbound / outbound timestamp
unread count
inbound / outbound count in last 14 days
total message count in last 14 days

Intent Signals

lead_score
SMS tracked link clicks
email opens and clicks

Appointment Signals

next appointment time
appointment count

Important Exclusions

Closed / Suppressed Lead Statuses

Contacts are excluded from intent-based buckets when lead status is: DNC, CLOSED, NOT INTERESTED, APPOINTMENT SET, WON.

Negative Click URLs

The system ignores opt-out style links (unsubscribe, opt-out, opt.customerconnects.app) to prevent false positives.

Architecture Overview

                     AGENT RECOMMENDED ACTIONS

  Assigned contacts
        |
        +----------------------------+
        |                            |
        v                            v
  Conversation signals         Intent signals
  - inbound/outbound           - lead score
  - unread count               - SMS link clicks
  - message counts             - email opens/clicks
        |                            |
        +-------------+--------------+
                      |
                      v
         Supabase RPC: get_agent_recommendations()
                      |
          ranked rows by recommendation_type
                      |
                      v
     frontend hook: useAgentRecommendations()
                      |
        +-------------+-------------+
        |                           |
        | RPC available             | RPC missing / unavailable
        v                           v
  use SQL-ranked rows         use client-side fallback ranking
        |                           |
        +-------------+-------------+
                      |
                      v
      AgentMetricsDashboard -> Recommended Actions card

Frontend Files

File	Purpose
`frontend/src/hooks/useAgentRecommendations.js`	Fetches and groups recommendations, prefers RPC, falls back to client ranking
`frontend/src/components/livechat/AgentMetricsDashboard.js`	Renders the Recommended Actions card and section UI
`supabase/migrations/20260315_create_agent_recommendations_rpc.sql`	Supabase ranking logic and indexes

Deployment SOP

Step 1. Apply the migration

Run the full SQL from: supabase/migrations/20260315_create_agent_recommendations_rpc.sql

Step 2. Hard refresh the app

Ensures the newest frontend bundle is loaded.

Step 3. Open the dashboard

Open the LiveChat metrics/dashboard view that contains the Recommended Actions card.

Step 4. Verify bucket behavior

Contact with unread inbound → appears in Respond Now
Contact with recent tracked click → appears in Clicked Link
Contact waiting a few days after outbound → appears in Re-Engage
Warm active contact → appears in High Intent

QA Checklist

Product / Client QA

Recommended Actions card renders on the dashboard
Empty states are clean when no recommendations exist
Respond Now rows show reply-oriented copy
Clicked Link rows show click-oriented copy
Re-Engage rows show silent/follow-up copy
High Intent rows show engagement-oriented copy
Send to To Do creates a todo entry successfully

Technical QA

RPC exists in Supabase
Authenticated agent can load recommendations
Agent cannot request another agent's recommendations
Closed / DNC contacts do not appear in intent-based buckets
Unsubscribe / opt-out clicks do not create Clicked Link recommendations
Dashboard still works if RPC is temporarily unavailable

Troubleshooting

Card is empty

Does the agent have active assigned contacts?
Do assigned contacts have message or engagement signals?
Was the migration applied in the correct Supabase project?
Is the current user authenticated in the app?
Are contacts mostly in closed/disqualified statuses?

Clicked Link never appears

Check recent rows in short_link_clicks
Check matching shortened_links.contact_id
Verify clicks are not unsubscribe/opt-out URLs
Verify contacts are assigned to the current agent

SQL works but dashboard still looks old

Browser caching old frontend code — hard refresh
Wrong environment/project received the SQL
App is pointed at a different Supabase instance

Known Limitations

Email engagement reads from email_events; older workspaces not yet backfilled may under-rank some contacts.
Recommendation acceptance/rejection is not yet logged as a dedicated feedback system.

Future Improvements

Add recommendation outcome logging
Show direct drill-through into the contact thread from each row
Expose a small debug/admin panel showing bucket counts and raw signals
Backtest and tune score weights against conversion outcomes