# WACM Flowmaker Visual Automation API (v1)

Base URL: `https://app.wacm.in/api/v1/flowmaker`
Authentication: `Authorization: Bearer <TOKEN>` or `?token=<TOKEN>`

## Endpoints
- **GET /api/v1/flowmaker/flows**: List flows (filters: `active`, `search`, `page`, `limit`). Returns `id`, `name`, `active`, `has_unpublished_changes`, `last_published_at`, `node_count`, `edge_count`, `node_types`, `trigger_types`.
- **GET /api/v1/flowmaker/flows/{id}** (or **GET /api/v1/flowmaker/flows/show?flow_id={id}**): Full flow definition including `nodes`, `edges`, and `raw_flow_data`.
- **POST /api/v1/flowmaker/flows**: Create flow (`name`, `active`, `publish`, `nodes`, `edges`). Validates graph integrity before saving.
- **PUT /api/v1/flowmaker/flows/{id}**: Update flow (`name`, `active`, `publish`, `nodes`, `edges`). Supports draft saving (`publish: false`) and live publishing (`publish: true`).
- **POST /api/v1/flowmaker/flows/{id}/toggle-active**: Toggle or explicitly set `active` status (includes preflight graph validation).
- **POST /api/v1/flowmaker/flows/{id}/duplicate**: Clone an existing flow as an inactive draft copy.
- **POST /api/v1/flowmaker/flows/{id}/discard-draft**: Revert unpublished draft edits back to `published_flow_data`.
- **DELETE /api/v1/flowmaker/flows/{id}**: Delete a flow and its execution history.
- **POST /api/v1/flowmaker/flows/validate**: Dry-run structural validation of `nodes` and `edges` (returns `valid`, `errors`, `warnings`, `summary`).
- **POST /api/v1/flowmaker/flows/ai-generate**: Generate a complete Flowmaker node/edge graph from a natural-language `prompt` (optional `auto_create: true`).
- **GET /api/v1/flowmaker/node-types**: List all supported trigger, message, logic, integration, and CRM node types with their `settings_schema`, incoming/outgoing edge handles, runtime variables, and routing rules.
- **GET /api/v1/flowmaker/history**: Paginated step-by-step execution history (filters: `flow_id`, `contact_id`, `status`, `node_type`, `limit`).
- **DELETE /api/v1/flowmaker/history**: Clear execution history (optional `flow_id`, `contact_id`, `before_date`).

## Flow Graph Schema Specifications
A flow graph contains `nodes` (array) and `edges` (array).

### Node Structure:
```json
{
  "id": "node_1",
  "type": "quick_replies",
  "position": { "x": 350, "y": 200 },
  "data": {
    "label": "Confirm Action",
    "settings": { ... }
  }
}
```

### Edge Structure:
```json
{
  "id": "e_node_1_to_node_2",
  "source": "node_1",
  "target": "node_2",
  "sourceHandle": "button-1_id12345",
  "targetHandle": null
}
```

## Key Node Types & Edge Routing Handle Conventions

### 1. In-Session Reply Buttons (`buttons` or `quick_replies`)
Sends interactive buttons within the active 24-hr WhatsApp window.
- **data.settings**:
  - `body` *(string, required)*: The text message body (do not use `message`).
  - `activeButtons` *(integer, 1-3, required)*: Number of active buttons.
  - `button1` *(string, required, max 20 chars)*: Label for button 1.
  - `button2` *(string, optional, max 20 chars)*: Label for button 2.
  - `button3` *(string, optional, max 20 chars)*: Label for button 3.
- **Edge Routing Handles**: **1-indexed**!
  - `button-1` (matches button 1 tap)
  - `button-2` (matches button 2 tap)
  - `button-3` (matches button 3 tap)

### 2. WhatsApp Meta Template (`template`)
Sends an approved Meta WhatsApp template (required if 24-hr service window might be closed).
- **data.settings**:
  - `selectedTemplateId` *(number, required)*: Local WACM template ID.
  - `parameters` *(object, optional)*: Key-value map of template variable values: `{ "BODY_1": "{{order_customer_name}}", "BODY_2": "{{order_total_amount}}" }`.
- **Edge Routing Handles**:
  - `quick-reply-0` *(0-indexed)*: Matches first quick reply button tap.
  - `quick-reply-1` *(0-indexed)*: Matches second quick reply button tap.
  - `quick-reply-2` *(0-indexed)*: Matches third quick reply button tap.
  - `always`: Continues unconditionally and immediately without waiting for a customer reply (use for parallel timers/followups).

### 3. Conditional Branch (`branch`)
Branches execution path based on variable values.
- **data.settings**:
  - `conditions` *(array of objects)*: `[{ "variable": "order_payment_method", "operator": "contains", "value": "COD" }]`.
    - Operators: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `greater_than`, `less_than`, `matches_regex`.
  - `logicType` *(string, default "and")*: `"and"` or `"or"`.
- **Edge Routing Handles**: strictly `"true"` and `"false"`.

### 4. Staff / External Alert Message (`send_ext_message`)
Sends an external WhatsApp notification message to a team member or operations phone.
- **data.settings**:
  - `phone` *(string, required)*: Recipient phone number with country code (e.g. `"919662775074"`).
  - `message` *(string, required)*: Text message content, supports all runtime variables.
- **Edge Routing Handle**: `always`.

### 5. Order Created Webhook Trigger (`order_created`)
Fires when an order is created via Shopify, WooCommerce, or WACM Shop webhook.
- Automatically populates the following runtime variables:
  - `{{order_order_id}}`: Numeric internal/store order ID.
  - `{{order_order_number}}`: Customer-facing order number (e.g. `#1042`).
  - `{{order_total_amount}}`: Formatted total price (e.g. `999.00`).
  - `{{order_payment_method}}`: Payment gateway/method name (e.g. `Cash on Delivery (COD)` or `Prepaid / Razorpay`).
  - `{{order_customer_name}}`: Customer full name.
  - `{{order_customer_phone}}`: Shipping phone number with country code.
  - `{{order_customer_address}}`: Complete multi-line shipping address.
  - `{{order_items_text}}`: Formatted item summary string.
  - `{{order_currency_symbol}}`: Currency code or symbol (e.g. `₹` or `INR`).
