# WhatsApp Enrollment Journey

## Goal

The WhatsApp Enrollment Journey converts a WhatsApp conversation into a paid enrollment and first-session attendance without leaving ECOLE ECOIN.

Arabic operational guide for staff: `docs/whatsapp_enrollment_journey_workflow_ar.md`.

Workflow:

1. Incoming WhatsApp message.
2. WhatsApp contact and conversation are created or updated.
3. A WhatsApp lead is created for course or event interest.
4. Support qualifies the lead from the inbox.
5. Support recommends a course and cohort.
6. Authorized staff creates an enrollment from the conversation.
7. The system creates a deposit payment using the existing cohort billing policy.
8. Payment confirmation moves the conversation to confirmed.
9. First-session attendance moves the conversation to attended.
10. No-show follow-up can move the conversation to no_show and queue a follow-up message.

## Stages

- `new`: first inbound message or unqualified lead.
- `interested`: early interest captured.
- `qualified`: staff confirmed that the prospect is relevant.
- `course_recommended`: course and cohort were recommended.
- `enrollment_started`: enrollment work started.
- `payment_pending`: deposit payment is required.
- `confirmed`: deposit was approved and the seat is confirmed.
- `attended`: first session was attended.
- `no_show`: first session was missed.
- `lost`: staff closed the opportunity.

## Data Model

New tables:

- `whatsapp_leads`: WhatsApp-specific lead linked to a contact, desired course, desired cohort, and status.
- `whatsapp_conversation_events`: audit-style timeline of stage/action events.

Updated tables:

- `whatsapp_contacts.lead_id`: current active WhatsApp lead.
- `whatsapp_conversations.stage`: conversion stage used by admin inbox and automation.

## Enrollment Creation

From `/admin/messaging/whatsapp/conversations/{conversation}`, staff with `whatsapp.enrollment.create` can create an enrollment.

The action:

- Uses the contact phone as `phone_e164`.
- Creates a `Registration` with source `whatsapp`.
- Creates an `Enrollment` with a pricing snapshot from `BillingPlanFactory`.
- Creates a `Payment` for the required deposit.
- Moves the conversation to `payment_pending`.
- Queues a WhatsApp outbox message with payment instructions.

## Deposit Policy

Deposit values are not hardcoded in the WhatsApp module. The service asks `BillingPlanFactory` for:

- `total_amount_dzd`
- `deposit_required_dzd`
- `balance_due_dzd`
- `purpose`
- `payment_stage`

This keeps WhatsApp enrollment aligned with the same payment rules used by normal registration.

## Payment Confirmation

When the existing `PaymentConfirmed` event is dispatched, the WhatsApp journey listener:

- Finds the conversation linked to the enrollment.
- Moves the stage to `confirmed`.
- Updates the linked WhatsApp lead.
- Records a `deposit_confirmed` conversation event.

## Attendance

When attendance is saved and the enrollment is marked present or late in the first session, the existing attendance workflow now also:

- Moves the WhatsApp conversation to `attended`.
- Resolves the conversation.
- Records a `first_session_attended` event.

No-show follow-up is exposed through `WhatsAppEnrollmentJourneyService::markNoShow()` for scheduler or admin workflows.

## Permissions

- `whatsapp.inbox.view`: access inbox.
- `whatsapp.conversations.reply`: reply from conversation.
- `whatsapp.conversations.assign`: assign conversations.
- `whatsapp.templates.send`: send recommendation or journey templates.
- `whatsapp.enrollment.create`: create enrollment from conversation.
- `whatsapp.enrollment.link`: reserved for future manual linking.
- `whatsapp.settings.manage`: manage direct integration settings.

Support users can handle conversations by default but do not receive `whatsapp.enrollment.create` automatically.

## Templates

Seeder templates added:

- `whatsapp_lead_welcome`
- `whatsapp_qualification_question`
- `whatsapp_course_recommendation`
- `whatsapp_enrollment_created`
- `whatsapp_deposit_payment_instructions`
- `whatsapp_transfer_upload_request`
- `whatsapp_seat_confirmed`
- `whatsapp_attendance_confirm_request`
- `whatsapp_attendance_24h`
- `whatsapp_attendance_3h`
- `whatsapp_no_show_followup`
- `whatsapp_lost_followup`

Run:

```bash
php artisan db:seed --class=WhatsAppTemplatesSeeder
```

## Demo Seeder

To see the full WhatsApp enrollment funnel with realistic demo conversations, run:

```bash
php artisan db:seed --class=WhatsAppEnrollmentJourneyDemoSeeder
```

The seeder creates 10 conversations, one for each stage:

- `new`
- `interested`
- `qualified`
- `course_recommended`
- `enrollment_started`
- `payment_pending`
- `confirmed`
- `attended`
- `no_show`
- `lost`

It also creates:

- One demo course.
- One demo cohort.
- Demo admin/support users.
- WhatsApp contacts and leads.
- Timeline inbound/outbound messages.
- Conversation events.
- Demo registrations, enrollments, and deposit payments for the later stages.

The demo data uses the prefix `DEMO-WA-*` and can be seeded multiple times safely.

## Conversion Metrics

Managers can measure the funnel by counting conversations or leads by stage:

- New leads.
- Qualified leads.
- Course recommendations.
- Enrollment started.
- Payment pending.
- Confirmed seats.
- Attended first sessions.
- No-shows.
- Lost opportunities.

## Limitations

- Keyword routing is deterministic and rule-based; no AI routing is used.
- No-show detection is service-ready but should be wired to a scheduled command if fully automated follow-up is required.
- Free-text Cloud API replies still depend on Meta’s customer service window and template rules.