whatsapp-flows

What this skill does

# WhatsApp Flows Skill

Build conversational WhatsApp experiences with dynamic forms, conditional logic, and server integration.

## Quick Start

### What are WhatsApp Flows?

WhatsApp Flows are structured conversations that collect user input through a series of screens. Use them to:
- Collect information (forms, surveys)
- Implement conditional logic (eligibility checks, branching)
- Display dynamic data (products, prices, inventory)
- Validate user input server-side
- Complete multi-step processes

### 5 Key Concepts

1. **Screens** - Individual steps in your flow. Each has a unique ID and layout.
2. **Components** - Building blocks (TextInput, Dropdown, Footer, If, etc.)
3. **Form Data** - User input via `${form.field_name}` binding
4. **Server Data** - Dynamic data via `${data.field_name}` binding
5. **Actions** - What happens: navigate, data_exchange, complete, update_data, open_url

### Minimal Example

```json
{
  "version": "7.1",
  "screens": [
    {
      "id": "GREETING",
      "title": "Greeting",
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextHeading",
            "text": "Welcome!"
          },
          {
            "type": "TextBody",
            "text": "Please tell us your name to proceed.",
            "markdown": true
          },
          {
            "type": "TextInput",
            "name": "name",
            "label": "What's your name?",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Continue",
            "on-click-action": {
              "name": "navigate",
              "next": {
                "type": "screen",
                "name": "CONFIRMATION"
              }
            }
          }
        ]
      }
    },
    {
      "id": "CONFIRMATION",
      "title": "Confirmation",
      "terminal": true,
      "success": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextHeading",
            "text": "Hello ${screen.GREETING.form.name}!"
          },
          {
            "type": "Footer",
            "label": "Done",
            "on-click-action": {
              "name": "complete",
              "payload": {
                "name": "${screen.GREETING.form.name}"
              }
            }
          }
        ]
      }
    }
  ]
}
```

**Business 3.0 API Requirements:**
- Every screen MUST have a `title` property
- Action properties use `name` (not `action`) with nested structure

**When to add `data_api_version`:**
- Only include `"data_api_version": "3.0"` if your flow needs server integration (data validation, dynamic data, form submission to backend)
- If your flow is client-side only with no backend endpoints, omit this property
- See [server-integration.md](reference/server-integration.md) for details on setting up endpoints

---

## Business 3.0 API Requirements

WhatsApp Flows uses the Business 3.0 API which has specific requirements:

**Every screen MUST have:**
- `id` (required) - Unique screen identifier
- `title` (required) - Screen title for display and navigation

**Markdown formatting:**
- Only **TextBody** and **TextCaption** support markdown
- Set `"markdown": true` to enable formatting
- **TextHeading does NOT support markdown** (will cause validation error)
- Markdown is disabled by default if property omitted

**Optional server integration:**
- `data_api_version: "3.0"` - Only required if your flow calls backend endpoints
- `routing_model` - Only required with `data_api_version` for dynamic routing

**Minimal structure (no backend needed):**
```json
{
  "version": "7.1",
  "screens": [
    {
      "id": "SCREEN_ID",
      "title": "Screen Title",
      "layout": { ... }
    }
  ]
}
```

**With server integration (backend endpoints):**
```json
{
  "version": "7.1",
  "data_api_version": "3.0",
  "routing_model": { ... },
  "screens": [
    {
      "id": "SCREEN_ID",
      "title": "Screen Title",
      "layout": { ... }
    }
  ]
}
```

See **[constraints.md](reference/constraints.md)** for complete validation rules and **[server-integration.md](reference/server-integration.md)** for endpoint setup.

---

## Essential Constraints

| Item | Limit | Impact |
|------|-------|--------|
| Components per screen | 50 | Split into multiple screens if exceeded |
| Nesting depth (If/Switch) | 3 levels | Simplify logic or use separate screens |
| Flow JSON size | 10MB | Compress or split large flows |
| Text heading length | 80 chars | Be concise with titles (NO markdown) |
| Text body length | 4096 chars | Supports markdown v5.1+ (set `markdown: true`) |
| Dropdown options | 200 (static) | Use dynamic data for more options |
| Image max size | 300KB | Optimize images before including |
| Image count per screen | 3 | Limit media usage per screen |
| Screen title | Required | Business 3.0 API requirement |

See **[constraints.md](reference/constraints.md)** for complete reference.

---

## Core Reference Files

Navigate to these for detailed guidance:

### Components
**[reference/components.md](reference/components.md)** - All 22 components with syntax and examples
- Text: TextHeading, TextSubheading, TextBody, TextCaption, RichText
- Input: TextInput (7 types), TextArea, DatePicker
- Selection: Dropdown, CheckboxGroup, RadioButtonsGroup, OptIn, ChipsSelector, NavigationList
- Media: Image, ImageCarousel
- Actions: Footer, EmbeddedLink
- Logic: If, Switch

### Actions
**[reference/actions.md](reference/actions.md)** - Control flow progression
- `navigate` - Move to next screen
- `data_exchange` - Send to server, receive next screen
- `complete` - End flow with response
- `update_data` - Update screen state (v6.0+)
- `open_url` - Open external link (v6.0+)

### Data Binding
**[reference/data-binding.md](reference/data-binding.md)** - How to reference data
- Form data: `${form.field_name}`
- Server data: `${data.field_name}`
- Global references: `${screen.SCREEN_ID.form.field}`
- Nested expressions: `${`...`}` (v6.0+)

### Conditional Logic
**[reference/conditional-logic.md](reference/conditional-logic.md)** - If and Switch components
- Boolean conditions with If
- Multi-way branching with Switch
- Nested conditionals (max 3 levels)
- Conditional navigation and inputs

### Server Integration
**[reference/server-integration.md](reference/server-integration.md)** - Backend integration
- Routing models for flow control
- Data endpoints (request/response format)
- Dynamic data from server
- Error handling and validation

### Constraints & Validation
**[reference/constraints.md](reference/constraints.md)** - Limits and rules
- Character limits per component
- Component counts per screen
- Validation checklist
- Common errors and fixes

### Security & Best Practices
**[reference/security.md](reference/security.md)** - Secure flows
- Sensitive data handling
- HTTPS requirements
- Input validation patterns
- GDPR compliance

### Versions & Features
**[reference/versions.md](reference/versions.md)** - Feature matrix v4.0-7.1
- Component availability by version
- Breaking changes between versions
- Migration guide
- Version recommendations

### Navigation
**[reference/TABLE_OF_CONTENTS.md](reference/TABLE_OF_CONTENTS.md)** - Find what you need
- By topic, use case, component type
- Quick reference guides

---

## Examples

See **[examples.md](examples.md)** for 4 complete, working flows:

1. **Simple Multi-Screen Survey** - Basic form with navigation
2. **Conditional Age Verification** - If/Switch with routing decisions
3. **E-Commerce Product Selection** - Dynamic data from server
4. **Server Validation Flow** - Email validation with error handling

---

## Common Tasks

### I need to add formatted text (bold, lists, emphasis)

1. Use **TextBody** or **TextCaption** components (not TextHeading)
2. Add `"markdown": true` property to enable formatting
3. Use markdown syntax: `**bold**`, `*italic*`, `\n` for line breaks, `•