[Campaigns] Add answering-machine detection, voicemail, dispositions, callbacks, and follow-up journeys

[rahuliitk]

Parent epic: #79

Priority: P1 — product completion

Problem and current baseline

QuickVoice already places outbound batch calls, runs voice agents, transfers calls, and records call status/transcripts/extracted fields. Campaign outcomes beyond completed/failed are not yet modeled as a coherent system: answering-machine detection (AMD), voicemail behavior, business dispositions, callback commitments, and subsequent follow-up steps can be inconsistent or handled manually. This issue adds outcome-aware orchestration on top of existing calls/campaigns; it does not rebuild telephony or guarantee carrier detection accuracy.

User-visible outcome

Campaign operators can choose what happens when a person, machine, fax/unknown endpoint, or no answer is detected; configure an approved voicemail; capture structured dispositions; schedule and fulfill callbacks in the recipient’s local time; and run bounded, consent-aware follow-up journeys. Every step is explainable, cancellable, and linked to the customer/campaign history.

Requirements

• Define normalized answer classifications with provider evidence/confidence: human, machine-start, machine-end/beep, fax, silence, no-answer, busy, invalid/unreachable, unknown, and provider error; preserve raw provider values separately.
• Add per-campaign/provider AMD policy: disabled, synchronous, asynchronous, or platform-assisted where supported; detection timeout, early speech behavior, unknown fallback, and explicit customer-experience tradeoff preview.
• Let campaigns select outcome actions: start agent, continue while detecting, wait for beep, play/drop approved voicemail, hang up, schedule eligible retry, create callback/task, transfer/fallback, or mark terminal disposition.
• Support recorded audio or approved text-to-speech voicemail versions with locale/voice, duration, disclosure/identity, callback information, opt-out policy, effective dates, approval, test preview, and provider capability validation.
• Ensure voicemail playback/drop is an idempotent side effect and cannot occur twice for one attempt because of callbacks/worker retries.
• Define organization-configurable disposition catalog with stable code, label, category, terminal/retryable, success/conversion flags, required notes/fields, follow-up policy, visibility, version, and deprecation rules. Retain provider/system disposition separately from human/AI/business disposition.
• Allow agents/workflows, provider events, automations, and authorized reviewers to propose/set dispositions with provenance/confidence; configured high-impact dispositions require validation or human review.
• Support callback request/commitment with customer/channel, reason, owner/queue/agent, recipient timezone/window, earliest/latest time, priority, status, source call, notes/context summary, and attempts; prevent duplicate active commitments.
• Provide reminder, claim/assign, reschedule, complete, cancel, missed/expired, and escalation behavior; re-check contactability/quiet hours before outbound fulfillment.
• Model bounded follow-up journeys as immutable-versioned steps triggered by disposition/outcome, with wait/delay, call/SMS/task/webhook where available, exit criteria, maximum steps/attempts/duration, goal reached, opt-out/DNC stop, and cancellation.
• Show recipient journey timeline spanning attempts, classifications, voicemails, dispositions, callbacks, follow-ups, and terminal reason.

API, data, and event implications

• Add normalized answer-classification evidence, voicemail asset/version/approval, disposition definition/version/assignment, callback commitment/attempt, journey definition/version/enrollment/step, and transition records linked to customer/campaign/call/workflow IDs.
• Expose CRUD/test/approve APIs for voicemail/dispositions; callback list/claim/assign/reschedule/complete/cancel; journey draft/validate/start/stop/status; all with organization scoping, optimistic concurrency/idempotency, and stable reason codes.
• Emit AMD started/classified/timeout/overridden, voicemail queued/started/completed/failed/unknown, disposition proposed/set/changed, callback lifecycle, journey enrolled/step scheduled/executed/skipped/stopped, opt-out, and terminal events.
• Webhooks/analytics use normalized codes and also retain provider/raw evidence for diagnosis; no hidden reasoning, credentials, or disallowed PII in event payloads.

UX and accessibility

• Campaign preflight shows provider AMD support, expected latency/false-classification tradeoffs, selected unknown behavior, voicemail preview/version, and which outcomes cause retry/callback/follow-up.
• Disposition controls are searchable, keyboard operable, require configured fields, distinguish system/AI/human sources, and avoid ambiguous free-text-only reporting.
• Callback queue supports owner/timezone/due/status/priority filters, accessible reminders, clear local/organization time, and conflict-safe claim/reschedule actions.
• Journey builder/review presents a linear/graphical path plus a text outline, explicit stop conditions, maximum exposure, and per-step consent/channel requirements.
• Status and confidence never rely on color alone; audio has text/transcript alternatives where appropriate.

Security, privacy, compliance, provider, and cost boundaries

• Enforce least-privilege permissions for voicemail upload/approval, disposition definition/override, callback access/assignment, and journey publish/control; audit changes and manual overrides.
• Scan/validate uploaded audio and protect recordings/transcripts/notes/customer data under retention, DSAR, legal-hold, redaction, and export policies.
• Re-check [Contacts] Add customer profiles, lists, segments, consent, DNC, timezones, and suppression rules #117 contactability, opt-out/DNC/suppression, purpose, frequency, recipient-local time, and channel policy before every retry/callback/follow-up; an earlier commitment does not bypass a later opt-out.
• Customers configure applicable voicemail/recording/marketing/disclosure rules; the platform does not claim legal compliance or infer permission from detection.
• Provider-specific AMD/drop behavior is capability-gated. Unknown or unsupported results follow the configured safe path, never a guessed human/machine classification.
• Surface AMD, TTS, channel, and additional-attempt cost; journey budgets/limits are enforced before each step.

Failure and backward compatibility

• Late/conflicting provider classifications follow a documented precedence and update history; they do not start a second mutually exclusive action.
• Ambiguous voicemail/playback status remains unknown and is not replayed automatically when duplicate delivery is possible.
• Callback scheduling conflicts, timezone changes, assignment races, worker restarts, and missed windows converge on one commitment state with an audit trail.
• Opt-out, campaign cancellation, customer deletion policy, goal reached, or journey expiry stops queued future steps immediately according to durable cancellation rules.
• Existing call statuses/transcripts and campaign reporting remain intact; legacy outcomes map to normalized codes without rewriting historical provider evidence.

Dependencies

• [Contacts] Add customer profiles, lists, segments, consent, DNC, timezones, and suppression rules #117 contactability/customer timeline.
• [Campaigns] Add lifecycle controls, pacing, schedules, retries, concurrency, cancellation, and idempotency #120 campaign lifecycle, attempts, scheduling, idempotency, and controls.
• [Flows] Define a versioned workflow schema and publish/rollback lifecycle #88/[Flows] Expand the node catalog for subagents, decisions, tools, handoffs, data operations, waits, and terminal outcomes #92/[Flows] Add durable runtime state, retries, checkpoints, idempotency, and failure policies #97 for workflow/journey nodes and durable wait/resume where reused.
• Existing telephony providers, transfers, call logs, secrets, recordings, audit, and planned SMS/integration capabilities.

Out of scope

• Guaranteeing accurate human/machine classification or voicemail delivery across all carriers/devices.
• Unlimited marketing automation or channels not yet supported by QuickVoice.
• Automatic high-impact business decisions based solely on AI disposition.
• Circumventing opt-out/DNC/quiet-hours/provider rules through callbacks or journeys.

Acceptance criteria

• Every provider answer result maps to a normalized classification plus preserved raw evidence/confidence and a single deterministic configured action.
• AMD/voicemail capability incompatibility and unknown behavior are visible at preflight and enforced at runtime.
• Duplicate/late events and worker retries cannot produce two voicemail drops, callbacks, or mutually exclusive outcome actions for one attempt.
• Dispositions are versioned, provenance-aware, reportable, and drive only explicitly configured retry/follow-up behavior.
• Callback commitments are timezone-aware, non-duplicative, assignable/reschedulable/audited, and re-check contactability before fulfillment.
• Journeys are bounded, pinned to an immutable version, durable across restart, stop immediately on opt-out/DNC/cancellation/goal/expiry, and expose every step/reason.
• Existing calls/campaign statuses and historical evidence remain backward compatible.

Required tests

• Provider adapter contract/golden tests for every raw AMD/call result, synchronous/asynchronous timing, timeout, unknown, fax, beep, and late/conflicting callbacks.
• Idempotency/fault-injection tests for duplicate webhooks, worker crash, voicemail ambiguous outcome, callback races, journey restart, cancel versus due step, and provider outage.
• Disposition schema/version/provenance, required-field, deprecation, manual-override, retry mapping, and analytics reconciliation tests.
• Scheduling tests for callback/journey timezones, DST, due/missed windows, reschedule, frequency caps, and last-moment opt-out/suppression.
• Security/privacy tests for permissions, tenant isolation, audio upload scanning, redaction, retention/DSAR/legal hold, audit, and safe exports.
• Console end-to-end/accessibility tests for AMD policy, voicemail preview/approval, dispositions, callback queue, journey outline/builder, live timeline, keyboard use, and responsive layouts.