# Generate WhatsApp Flow

Generate a config-driven WhatsApp conversation flow JSON for the Helix Engage flow runtime engine.

## When to use

When the user asks to create a new WhatsApp flow, chatbot flow, or conversation automation — e.g., "create a WhatsApp flow for prescription refills", "build a feedback collection flow", "add a lab report flow".

## Flow Runtime Architecture

The flow engine reads JSON flow definitions from `src/messaging/flow/default-flows/` and executes them at runtime. Each flow is a graph of **Groups** (containers) containing **Blocks** (steps), connected by **Edges**.

### Execution Model

```
Inbound WhatsApp message → match flow by trigger → create/resume session
→ walk forward through Groups → Blocks:
    MessageBlock → send text/buttons/list to patient
    InputBlock → PAUSE, wait for next message
    ConditionBlock → evaluate variable, follow matching edge
    SetVariableBlock → assign/transform variable
    ToolCallBlock → call registered tool
    AIBlock → generate LLM response
    JumpBlock → jump to another group
→ End of group → follow outgoing edge → next group
→ No more edges → flow complete, session cleared
```

Session state stored in Redis with 24h TTL. Per-phone execution lock prevents concurrent flows.

### Flow JSON Schema

```typescript
type Flow = {
    id: string;                     // "flow-{kebab-name}"
    name: string;                   // Human-readable name
    description: string;            // Admin-facing description
    trigger: FlowTrigger;           // What starts this flow
    groups: Group[];                // Ordered containers of blocks
    edges: Edge[];                  // Connections between blocks/groups
    variables: VariableDefinition[];// Flow-scoped variables
    version: number;                // Start at 1
    status: 'draft' | 'published'; // Only published flows execute
};

type FlowTrigger =
    | { type: 'message'; conditions?: { keywords?: string[]; regex?: string } }
    | { type: 'default' };          // Catch-all when no other flow matches

type Group = {
    id: string;                     // "g1", "g2", etc.
    title: string;                  // "Greeting", "Department Selection"
    blocks: Block[];                // Executed in order
};

type Edge = {
    id: string;                     // "e1", "e2", etc.
    from: { blockId: string; conditionId?: string };
    to: { groupId: string; blockId?: string };
};

type VariableDefinition = {
    id: string;                     // "v1", "v2", etc.
    name: string;                   // "selectedDepartment"
    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
    defaultValue?: any;
};
```

### Block Types

```typescript
// Send text, buttons, or list to patient
type MessageBlock = {
    id: string; type: 'message';
    content:
        | { format: 'text'; text: string }  // Supports {{variables}}
        | { format: 'buttons'; text: string; buttons: { id: string; title: string }[] }  // Max 3 buttons, title max 20 chars
        | { format: 'list'; text: string; buttonText: string; sections: { title: string; rows: { id: string; title: string; description?: string }[] }[] };  // Section title max 24 chars, row title max 24 chars, max 10 rows total
};

// Wait for patient reply — PAUSES execution
type InputBlock = {
    id: string; type: 'input';
    inputType: 'text' | 'interactive_reply' | 'any';
    variableId: string;             // Store reply in this variable
    validation?: { regex?: string; errorMessage?: string };
};

// Branch based on variable value
type ConditionBlock = {
    id: string; type: 'condition';
    conditions: {
        id: string;                 // "c1" — used in edge.from.conditionId
        variableId: string;
        operator: 'equals' | 'contains' | 'exists' | 'not_exists' | 'gt' | 'lt' | 'starts_with';
        value?: string;             // Supports {{variables}}
    }[];
};

// Assign or transform a variable
type SetVariableBlock = {
    id: string; type: 'set_variable';
    variableId: string;
    value: string;
    expression?: 'extract_id' | 'extract_datetime' | 'date_tomorrow' | 'date_day_after';
    // extract_id: "doc:{uuid}:{name}" → uuid (second segment)
    // extract_datetime: "slot:{id}:{datetime}" → datetime (third+ segments, rejoined with :)
    // date_tomorrow/date_day_after: computes date string YYYY-MM-DD
};

// Execute a registered tool
type ToolCallBlock = {
    id: string; type: 'tool_call';
    toolName: string;               // Must be a registered tool (see below)
    inputs: Record<string, string>; // Values support {{variables}} and {{var.field}} dot notation
    outputVariableId?: string;
};

// Generate dynamic LLM response
type AIBlock = {
    id: string; type: 'ai';
    prompt: string;                 // Supports {{variables}}
    outputVariableId?: string;
    sendToPatient: boolean;         // true = send as WhatsApp message
};

// Jump to another group
type JumpBlock = {
    id: string; type: 'jump';
    targetGroupId: string;
};
```

### Available Tools (ToolRegistry)

| Tool Name | Description | Inputs | Output |
|---|---|---|---|
| `resolve_caller` | Phone → Lead + Patient | phone? (defaults to current) | { leadId, patientId, isNew, phone } |
| `send_department_list` | Interactive department list | (none) | { sent, departments[] } |
| `send_doctor_list` | Interactive doctor list | department | { sent, count } |
| `send_slot_list` | Time slots for doctor+date | doctorId, doctorName, date | { sent, slots } |
| `send_confirm_buttons` | Confirm/Cancel buttons | summary | { sent } |
| `book_appointment` | Book with conflict check | patientName, phoneNumber, department, doctorName, scheduledAt, reason | { booked, appointmentId, reference } |
| `lookup_appointments` | Check existing appointments | (none — uses current caller) | { appointments[] } |
| `send_appointment_qr` | Generate and send QR code | appointmentId, reference, patientName, doctorName, department, scheduledAt | { sent, qrUrl } |

### System Variables (auto-injected)

| Variable | Description |
|---|---|
| `_initialMessage` | The first message the patient sent |
| `_senderName` | WhatsApp profile name |
| `_phone` | Phone number (E.164 without +) |
| `_callerName` | Resolved patient name from platform |
| `_leadId` | Lead ID if exists |
| `_patientId` | Patient ID if exists |
| `_isNew` | true if no prior records |

### Variable Interpolation

- `{{variableName}}` — simple substitution
- `{{result.fieldName}}` — dot notation for object fields (e.g., `{{bookingResult.appointmentId}}`)
- Interactive reply IDs stored in `variableId`, display titles in `variableId_title`

### WhatsApp Constraints

- Button title: max 20 characters
- List section title: max 24 characters
- List row title: max 24 characters
- List row description: max 72 characters
- Max 3 buttons per message
- Max 10 list rows total across all sections
- No markdown in text messages (plain text only)
- Interactive messages only work within 24h session window

## How to Generate

1. **Ask the user** what the flow should do — purpose, steps, what data to collect
2. **Design the groups** — each logical phase is a group (Greeting, Selection, Confirmation, etc.)
3. **Define variables** — what data flows through the conversation
4. **Build blocks** — MessageBlocks for output, InputBlocks to pause for reply, ConditionBlocks for branching, ToolCallBlocks for platform operations, AIBlocks for dynamic responses
5. **Wire edges** — connect groups via edges, condition edges for branching
6. **Write the JSON** to `src/messaging/flow/default-flows/{flow-name}.json`
7. **Register new tools** if needed in `src/messaging/flow/tool-registry.ts`

## Reference

See `src/messaging/flow/default-flows/appointment-booking.json` for a complete working example with:
- AI greeting
- Intent routing (book / check / question)
- Interactive lists (departments, doctors, slots)
- Date selection with custom date AI parsing
- Confirmation buttons
- Booking with conflict check
- QR code generation

## Deployment

After creating the flow JSON:
1. `npm run build` — verifies the JSON is copied to dist (via nest-cli.json assets)
2. Deploy to EC2 — the flow store auto-seeds on first run if `data/flows/` is empty
3. If updating an existing flow: `docker exec sidecar cp /app/dist/.../flow.json /app/data/flows/flow-id.json && docker compose restart sidecar`