Phase 3 — Connect (Cold-Calling)

What this phase delivers: the targets who didn't reply to the Outreach emails flow into a managed cold-calling operation — a Supervisor schedules Connect-Agent shifts, the system feeds each shift the highest-benchmark unworked targets, agents call through them in a focused cockpit, and every outcome feeds KPIs and agent commissions.

This is the standout module. No competitor ships the workforce layer (shifts, gatekeeper KPIs, per-agent commissions, benchmark-driven queues), so most of this phase is build. The dialer itself is the one thing we integrate.

1. What we build vs. what we integrate (this phase)

We build the entire workforce layer: ConnectVariant windows and shift scheduling, the benchmark-driven call Packages, the agent cockpit, call-log capture (Call + PipelineEvent), the KPIs (reach rate, gatekeeper quote, interest rate, appointment rate), and per-agent commission tracking. This is the differentiator.

We integrate the power dialer / telephony only — placing calls, auto-advancing to the next number, recording, and live monitoring. That's a solved, commoditised problem; the client has already chosen CloudTalk for it.

So unlike Phases 1–2, this phase is one integration wrapped in a lot of custom software. The integration is its own NestJS module behind a "dialer" interface (mockable, retry + backoff, 30s timeout, secret-redacted logging, cost recorded, mocked in CI). Call sync runs on the connect-sync queue (BullMQ); inbound events arrive on webhooks.

2. Layer 1 — Power dialer / telephony

The engine that places and manages the actual calls. CloudTalk is the client's choice; the alternatives are listed for completeness only.

How each one works + docs

• CloudTalk — A REST API (HTTP Basic auth using an API Key ID + Secret). We push contacts / call lists to it, agents work through them with CloudTalk's power dialer (which auto-dials the next number as soon as a call ends), and CloudTalk fires webhooks on call events (call.started, call.answered, call.ended, call.missed, voicemail.received). We capture those events to build our Call logs and KPIs, and can pull the recording afterwards. Webhook payloads are signature-verified before they touch business logic. Docs: https://developers.cloudtalk.io
• Aircall — REST API (/v1 and /v2) with OAuth or Basic auth; you push contacts, receive call-event webhooks, and pull recordings, notes, and tags to sync into your own system. Docs: https://developer.aircall.io
• JustCall — REST API covering calls and SMS with a predictive dialer and CRM connectors; similar push-contacts / receive-events model. Docs: https://developer.justcall.io/docs/overview

Recommendation: proceed with CloudTalk as decided. We wrap it behind a single internal "dialer" interface so that if it ever needs replacing (its account-scoped key and undocumented rate limits are the main risks), we can swap it without touching the cockpit or KPI logic.

3. What we build — the workforce layer (the market gap)

This is the heart of the phase, described in plain terms:

• Connect-Agents — the real call-center staff, each with a commission rate. A Connect-Agent sees only released campaigns (nothing without a release).
• Connect variants — Supervisor-defined weekday/time windows (ConnectVariant) that shifts must fall inside, plus the ConnectSteps (the call script) attached to them, so different campaigns or tests can use different scripts and windows.
• Shifts & packages — a Supervisor assigns this agent × this campaign × this date/time × this many targets as a Shift, which falls inside a Connect variant's window. When the shift activates, the system automatically pulls the top-N unworked targets by benchmark score into call Packages (a Shift holds up to 4 Packages) and locks them to that shift, so the best targets are always worked first.
• Agent cockpit — a single focused screen showing the current target's full context (all the Phase 1 enrichment + benchmark + the Phase 2 email history), the script, and a disposition form. CloudTalk's power dialer auto-advances to the next call so the agent never dials manually. The cockpit is realtime via Socket.IO (CloudTalk event → UI in < 500ms), on per-user / per-shift / per-campaign channels.
• Call log — for each Call: outcome, whether the gatekeeper was reached, whether the decision-maker was reached, interest level, appointment booked, and duration. Most of this arrives automatically from CloudTalk's webhooks; the rest the agent fills in. Stage changes are recorded as PipelineEvents.
• KPIs — derived from the call logs: reach rate, gatekeeper quote (how often the gatekeeper passes the agent through), interest/trust rate, appointment rate, and per-agent commission.

Because the benchmark score carries through from Phase 1, the call queue is always in the same priority order the whole system agrees on.

The 8-stage connect pipeline

Targets → Not reached (follow-up) → Reached (gatekeeper blocked) → Reached (appointment interest) → Appointment scheduled → No interest (follow-up) → Finally rejected → Do not contact.

• Bandit success = Appointment scheduled. Failure = not reached / finally rejected / no interest / do-not-contact. Intermediate states (gatekeeper blocked, appointment interest) fire no event.

4. How the call flow works

Plain-language flow:

1. Phase 2 hands over the targets that got the 3-mail sequence and no reply.
2. The Supervisor schedules a shift (agent, released campaign, time window inside a Connect variant, target count).
3. On activation, the system locks the top targets by benchmark into packages on that shift and loads them into the agent's cockpit.
4. The agent works the queue; CloudTalk's power dialer places each call and auto-advances.
5. After each call the agent logs the disposition; CloudTalk's webhook confirms the call outcome, recording, and duration, and the cockpit updates live over Socket.IO.
6. The target's stage updates: appointment scheduled routes it toward Closing (Phase 4); finally rejected / no interest / do-not-contact closes it out; not reached can be re-queued as a follow-up.
7. Every logged call feeds the KPIs and the agent's commission automatically.

A separate follow-up / warm call-back path exists for existing contacts who need a call-back — kept distinct from cold-call shifts so the two don't mix in reporting.

5. Legal & compliance notes for this phase

Cold calling has its own rules, separate from email. As with the other phases, the full compliance layer is out of scope for v1 in this repo — the points below are design considerations for the legal opinion, not build items:

• UWG (German unfair-competition law) — unsolicited cold calls to businesses are restricted in Germany (they generally require at least a presumed/prior business interest). This shapes who may legally be called and how.
• Call recording consent — recording calls without proper consent is heavily restricted in Germany and can carry serious penalties. Any recording (CloudTalk's or ours) would need a compliant consent step built into the call flow.
• GDPR — call logs and recordings are personal data; retention limits and deletion handling apply here just as in earlier phases.

Recommendation: the German UWG/GDPR legal opinion should explicitly cover cold calling and call recording, not just email.

6. Decisions needed for Phase 3

1. Dialer: confirm CloudTalk (already chosen) — and confirm we get API credentials for it. (Stored encrypted in the settings table, set via UI.)
2. Shift model: confirm the assignment unit (agent × released campaign × datetime × target-count, up to 4 packages) and whether one agent can hold multiple concurrent shifts.
3. KPI definitions: lock exact definitions for gatekeeper quote, reach rate, and interest rate so everyone measures the same thing. ⚠️ Needs client sign-off.
4. Commission rules: how is Connect-Agent commission calculated — per appointment, per interested target, per close? ⚠️ Needs client sign-off.
5. Call recording consent: what consent step is legally required, and does CloudTalk's built-in handling suffice?
6. Legal sign-off: UWG opinion covering cold calling + recording — owner and deadline. ⚠️ Needs client sign-off.

Appendix — Documentation links

Rate limits, plan gating, and recording features are approximate and change — confirm on each provider's site. Part of the project docs — Phase 3 of 5.