Ads health & needs attention#

Ads break quietly. A token expires, a campaign keeps "running" with zero delivery, a form stops feeding the CRM, a cost per lead doubles overnight. Waiting for a human to notice is expensive — so the platform runs a deterministic health scanner across every client workspace, turns real problems into issues, and keeps chasing them until somebody closes the loop.

Who this is for#

• Agency staff (ads specialists, account managers, support) — the operational queue.

• Platform admins — oversight of all workspaces.

• Clients — what you get: fewer surprises, and your own "needs your attention" panel in the CRM.

• Difficulty: Medium

• Time: 10 minutes

• Prerequisites: None to read. Acting on issues requires access to the agency console or Super Admin.

What gets checked (and how often)#

The scanner (leadhub:meta-ops-scan) runs every 30 minutes over all client workspaces and raises an issue for:

Issues carry a severity — critical, warning or info — and are attached to the client workspace. When a condition clears, the scanner auto-resolves its issue; nobody has to remember to close it. The scan output is logged for operators: workspaces scanned, issues detected, auto-resolved, errors.

The issue lifecycle#

Open → Acknowledged → Resolved (and Reopen if it recurs).

The Needs Attention page (agency console and Super Admin, gated by meta.performance.view) shows the queue; its menu badge counts critical open issues (in red), so a bad morning is visible before the first client call.

Steps#

1. Work the queue (agency)#

1. Open Meta Ads → Needs Attention in the agency console.

Expected result: issues grouped with the client workspace, severity and age. Criticals first.

2. Acknowledge#

1. Open an issue and Acknowledge it.

Expected result: the team can see somebody owns it — no duplicate work, no pretending.

3. Fix, then resolve#

1. Fix the root cause (commonly: reconnect Meta, restart/repair the campaign, fix the form selection).
2. Mark the issue Resolved. If your fix was wrong, the scanner will reopen it — honesty guaranteed.

Expected result: the queue shrinks and the history shows who did what.

4. Read the daily brief (every morning)#

1. Open Meta Ads → Daily Brief (composed around 07:15 each day).

Expected result: one summary per day — total open issues needing attention and support items waiting on the agency — refreshed in place rather than spamming you. If the platform has an AI key configured, the brief includes a narration; without one, you get the same facts without prose.

5. Client-side: your own attention panel#

1. In the client CRM (/admin), the dashboard's Needs your attention panel lists CRM problems, not ad ones: new leads nobody contacted, leads untouched for 24 hours, high-value leads never called, and follow-ups past due.

Expected result: you always know which leads are being neglected — pair it with the agency's ad health work for the full picture.

Expected result#

Nothing rots silently: broken connections, spiking costs and dead campaigns become owned, severity-ranked issues; clear conditions close themselves; and a daily brief gives both sides the same story.

Common mistakes#

• Acknowledging without fixing. Acknowledgement is a signal, not a fix — the issue stays open until resolved.
• Resolving a critical to "clear the queue". The scanner re-detects it on the next pass; you have just lost 30 minutes.
• Expecting the scanner to be clever. It is deterministic by design (no AI guessing) — it checks known failure signatures, and its silence is not proof of health for unlisted problems. Humans still read dashboards.
• Ignoring the brief. It is short; that is the point.

Troubleshooting#

Technical details#

• Scanner: App\Services\MetaOps\MetaIssueScanner + App\Console\Commands\MetaOpsScan (leadhub:meta-ops-scan, every 30 minutes) — deterministic, no AI; creates/refreshes MetaIssue rows (open / acknowledged / resolved, severities critical / warning / info) and auto-resolves cleared ones. Log line: "Scanned %d workspace(s): %d issue(s) detected, %d auto-resolved, %d error(s)."
• Issue page: App\Filament\SuperAdmin\Pages\MetaNeedsAttention (agency + Super Admin) — lifecycle open → acknowledged → resolved with reopen; nav badge = open critical count; gated meta.performance.view.
• Daily brief: App\Console\Commands\MetaOpsBrief (leadhub:meta-ops-brief, daily 07:15) via MetaDailyBriefService — one row per day refreshed in place; covers attention open_total and support awaiting_agency; AI narration optional.
• Related watchdog: leadhub:meta-health pings every connection every 6 hours.
• Client-side panel: App\Filament\Widgets\LeadAttentionWidget (60-second cache) — categories not_contacted, untouched_24h, high_value_never_called, overdue_follow_ups.

Related guides#

• Meta overview — where health fits in the architecture.
• OAuth & permissions — the most common fix (re-authorising).
• Agency panel (Meta Ops) — the console that works this queue.
• Leads — the health badges on the sales side.