# Medium-intent webinar follow-up

## What it does

An opt-in alternative to the generic AI-call thanks: a completed funnel call whose
customer spoke and whose normalized intent is medium can start one existing approved
proactive WhatsApp flow with the original session's personal join link. Retell and Yunke
use the same branch; a split uses the control profile's policy for either arm.

A null policy preserves existing follow-ups. This change creates no flows/templates,
subscriptions or credentials, enables no runtime gate and sends nothing during development.
The new migration has been exercised only against an isolated test database.

## How it works

- `ai_call_profiles.followup_policy` is nullable JSON:
  `{"medium_webinar_flow_id": 123}`. It is routing, excluded from provider content hashes.
  Saving only this field preserves Retell synchronization and settings version.
- Configure an existing flow by UUID with `voice-agent:routing <control-slug>
  --medium-flow=<flow-uuid>`. It must be active, proactively triggered, on an active
  connected platform Cloud channel, with an approved non-authentication opener whose
  parameters pass the shared `TemplateStepValidator`. Its opener body parameters must
  include `{{webinar_link}}`; unknown variable references are rejected.
- `--no-medium-flow` restores legacy thanks for future calls. A call with an already
  frozen target keeps that intent; changing configuration cannot replace an uncertain
  dispatch with a generic thanks or a different flow. Pause the flow or the customer's
  contact to stop already queued work.
- `AiCallAftermath` selects this branch only for a real funnel source, supported medium
  intent and customer speech. An explicitly configured but unavailable flow leaves the
  analysis pending; it does not silently fall back to a generic thanks.
- `medium_webinar_target` freezes local flow/send/event IDs before dispatch. This is an
  intent, not a completion stamp: a worker may always recover a missing queue receipt
  using that same target. `medium_webinar_queued_at` is written only after acceptance.
- `StartAiCallWebinarFollowUp` uses the existing paced broadcast lane, a per-call lock,
  a captured 30-minute retry window and a limit of three actual exceptions. Busy starts
  can wait without spending exception retries. All payloads contain local IDs only.
- At execution, recheck the call, exact lead/send/session/funnel/slot association,
  current registration and reminder mute, session status, current phone and consent,
  flow/channel and approved opener. Cancelled/past/moved sessions and changed recipients
  stop locally with a fixed skip reason; no other session is selected.
- The existing `FunnelWhatsappComposer::variablesForAiCall()` builds the original registration's short join
  link. Only `name`, `event_title`, `event_date`, `event_time`, and `webinar_link` reach
  the flow variables. Login/ticket links are not minted. Provider IDs, transcripts and internal metadata do not enter this bag.
- The existing `StartProactiveFlow` owns contact identity, marketing opt-out, handoff,
  conversation slots and the frozen flow snapshot. `AdvanceFlowRun` owns its later
  messages, pacing, Cloud-window checks and send-time contact suppression.
- The AI-call origin lives in `meta.source`; the canonical campaign/sheet `started_by`
  value is preserved, including the engine's stop-on-failed-opener behavior.
- Run metadata records the exact call UUID, lead and original event. Every replay checks
  this record, including ended runs, before starting anything. A crash between run creation
  and its call receipt is recovered from that explicit association, not from phone/time.
  `medium_webinar_run_id` means a flow started, not that its messages were delivered.
- Refusal recorded on this call permanently suppresses its own old follow-up, even if an
  administrator subsequently allows future contact. No restriction is automatically lifted.
- Every drip tick and queued message rechecks the source call UUID and lead recorded on
  this flow. This also stops a flow whose WhatsApp contact has no linked user; it never
  infers or changes contact identity from a phone number. Missing call provenance pauses
  this AI-call branch. The shared engine's unrelated flows keep their existing behavior.

## Reference usage

```sh
# Configuration only; do not run against an application database without authorization.
php artisan voice-agent:routing welcome-call --medium-flow=<existing-approved-flow-uuid>
php artisan voice-agent:routing welcome-call --no-medium-flow
```

The approved flow opener can use `{{name}}` and `{{webinar_link}}` in its existing body
parameters. No template approval or live dispatch is implied by saving the policy.
`AiCallWebinarFollowUpTest` starts the actual local flow with fake queues, verifies the
original registration link and one run after completion/replay, checks contact/context
stops, and recovers a lost dispatch receipt across a policy change. No provider is called.

## Related files

- `database/migrations/2026_10_26_110000_add_followup_policy_to_ai_call_profiles.php`.
- `src/VoiceAgent/AiCallProfile.php`, `src/VoiceAgent/Repositories/AiCallProfileRepository.php`.
- `src/VoiceAgent/Services/AiCallWebinarFollowUp.php`, `src/VoiceAgent/Services/AiCallAftermath.php`.
- `app/Jobs/VoiceAgent/StartAiCallWebinarFollowUp.php`, `app/Console/Commands/SetAiCallRouting.php`.
- `src/Event/Support/FunnelWhatsappComposer.php`, `app/Jobs/Whatsapp/StartProactiveFlow.php`.
- `tests/Feature/VoiceAgent/AiCallWebinarFollowUpTest.php`.
