aircall-agent-activity*

Live Unlock agent KPI dashboard pulling direct from AirCall. Active hours, contacts, conversion rate, leads per hour, leads per contact. For Tom. Werner sign-off pending.

E1 Job

The app reads live call and availability data from AirCall and surfaces a single-screen activity dashboard covering every active Unlock agent. Active hours are calculated as time in "available" or "busy" (on-call) status, excluding AirCall break and custom-away periods. Tom gets a net productive-hours figure, not a raw login-time total.

Five KPIs refresh every 60 seconds. No manual AirCall export required.

Active Hours Contacts Conversion Rate Leads / Hour Leads / Contact

Why now. Unlock agents go live 1 Oct 2026. Roy needs a monitoring surface before the first week of operation. AirCall's native reporting requires manual date-range pulls and does not isolate break time from active-hour totals.

E2 Inputs

Source	Data	Pattern
AirCall REST /v1/users	Agent roster	On-load, 5 min cache
AirCall REST /v1/users/{id}/availability	Status per agent (available / busy / break)	Poll 60s
AirCall REST /v1/calls	Call records (duration, tags, agent)	Poll 60s, today filter
AirCall Webhooks optional uplift	Live availability + call events	Push (reduces polling lag)
Pipedrive TBD	Lead conversion status	Daily batch if opted

Conversion rate gate. Option A: AirCall outcome tags (2.0 Roy-days, AirCall-only). Option B: Pipedrive deal match by phone number (2.5 Roy-days, adds connector). Werner to decide at sign-off.

E3 Outputs

Output	Destination	Freq
Live dashboard	Cowork artifact or hosted URL	Auto-refresh 60s
Active Hours	Dashboard tile (HH:MM)	Live
Contacts	Dashboard tile (integer)	Live
Conversion Rate	Dashboard tile (%)	Live / daily if Pipedrive
Leads / Hour	Dashboard tile (decimal)	Live
Leads / Contact	Dashboard tile (decimal)	Live

Read-only confirmed. No write paths. Dashboard is display-only. No data written back to AirCall or Pipedrive.

E4 Integrations

V2.1 Position

Layer 3, ACID Suite / Sales Loop. Reads from Layer 5 (AirCall service connector, optionally Pipedrive). No writes to any canonical layer. Read-only posture confirmed.

Layer 3 Layer 5 read

AirCall REST API

Auth via API key (env config, not hard-coded). Rate limit: 60 req/min. Polling budget for up to 20 agents at 60s = within limit. At 30+ agents, polling auto-extends to 90s with no manual intervention.

AirCall v1 CONNECTOR

Pipedrive (TBD, Option B)

REST API, /deals filtered by phone number match. Requires phone number format normalisation step. +0.5 Roy-days. Only if Werner selects Option B for conversion rate.

Pipedrive TBD

systems*

Element 5 shows data flow between systems. Element 6 shows actor responsibilities. Werner uses both for different questions.

E5Systems Diagram, data flow Mermaid flowchart, read-only confirmed

flowchart LR subgraph sources["Input Sources"] AC["AirCall REST API\n(v1/users, calls, availability)"] ACW["AirCall Webhooks\n(optional uplift)"] PD["Pipedrive\n(TBD — Option B)"] end APP["aircall-agent-activity\nLayer 3, Sales Loop\nRefresh: 60s"] DASH["Live Dashboard\n(Cowork artifact\nor hosted URL)"] AC -->|"connector read, poll 60s 🔒"| APP ACW -.->|"live event push"| APP PD -. "conversion data, TBD" .-> APP APP -->|"renders"| DASH

E6Actor-Interactions Diagram, systems and actors Who owns this. Who is the day-one user. Who receives output.

Human actor System actor Active use Passive / tracked Brief / TBD

Werner reads these diagrams differently. E5 (data flow) answers "what does this app touch and in what order?" and drives the build-cost estimate. E6 (actor-interactions) answers "who owns this in production, who is the day-one user, who gets output passively?" and drives the handoff responsibility discussion.

werner sign-off*

Five decisions needed before this gets built. Built via Claude Code.

Decisions Required

Five questions Werner needs to answer before build starts

01 Conversion rate source. Option A: AirCall outcome tags, team tags calls as "lead generated" (2.0d, simpler, AirCall-only). Option B: Pipedrive deal match by phone number (2.5d, more accurate, adds connector). This is the gate question.

02 Time window. Default view is today. Rolling 7-day or week-to-date toggle needed?

03 Agent scope. All AirCall users on the Cloudworkz account, or a named Unlock team group? AirCall has team groupings. Scoping to a team is a single API filter change, no day-cost impact.

04 Dashboard host. Cowork artifact (Tom access only) or hosted Cloudflare Pages URL (shareable with team)? Already deployed to Cloudflare.

05 Push alerts in V1. Dashboard is pull-only by default. Should V1 include a Slack notification if an agent's active hours drop below a threshold mid-day? +0.5d if yes.

Open Risks

Three items Roy and Werner should resolve before go-live

Break-time consistency. Active hours depend on agents using AirCall's custom-away statuses for breaks. If agents do not tag breaks, active hours overcount. agents need a protocol brief before go-live. This is not a build problem but a team-behaviour dependency. Recommend Roy confirms with agents at onboarding.

Phone-number normalisation (Option B only). Pipedrive and AirCall must share the same phone format (e.g. +44 vs 07xxx). A normalisation step is needed before phone-match conversion counting can work reliably. If this normalisation is not in place, Option B will produce incorrect conversion rates.

Rate limits at scale. 60 req/min covers 20 agents at 60s polling. At 30+ agents, polling auto-extends to 90s automatically, no manual intervention required. Roy sees a slight lag increase at that scale. Plan for a V2 webhook migration if Unlock grows past 30 agents before Oct 2026.

Brief V1 · 2026-06-01 · mini-app-brief skill V1.1 · Read-only posture confirmed

Werner sign-off: PENDING Friday session