Authoring WhatsApp Business Flows with validation, component guidance, and server integration patterns. Use when building conversational experiences, collecting user data, implementing conditional logic, or integrating with backend endpoints.
Build conversational WhatsApp experiences with dynamic forms, conditional logic, and server integration.
WhatsApp Flows are structured conversations that collect user input through a series of screens. Use them to:
${form.field_name} binding${data.field_name}{
"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:
title propertyname (not action) with nested structureWhen to add data_api_version:
"data_api_version": "3.0" if your flow needs server integration (data validation, dynamic data, form submission to backend)WhatsApp Flows uses the Business 3.0 API which has specific requirements:
Every screen MUST have:
id (required) - Unique screen identifiertitle (required) - Screen title for display and navigationMarkdown formatting:
"markdown": true to enable formattingOptional server integration:
data_api_version: "3.0" - Only required if your flow calls backend endpointsrouting_model - Only required with data_api_version for dynamic routingMinimal structure (no backend needed):
{
"version": "7.1",
"screens": [
{
"id": "SCREEN_ID",
"title": "Screen Title",
"layout": { ... }
}
]
}
With server integration (backend endpoints):
{
"version": "7.1",
"data_api_version": "3.0",
"routing_model": { ... },
"screens": [
{
"id": "SCREEN_ID",
"title": "Screen Title",
"layout": { ... }
}
]
}
See constraints.md for complete validation rules and server-integration.md for endpoint setup.
| 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 for complete reference.
Navigate to these for detailed guidance:
reference/components.md - All 22 components with syntax and examples
reference/actions.md - Control flow progression
navigate - Move to next screendata_exchange - Send to server, receive next screencomplete - End flow with responseupdate_data - Update screen state (v6.0+)open_url - Open external link (v6.0+)reference/data-binding.md - How to reference data
${form.field_name}${data.field_name}${screen.SCREEN_ID.form.field}${...} (v6.0+)reference/conditional-logic.md - If and Switch components
reference/server-integration.md - Backend integration
reference/constraints.md - Limits and rules
reference/security.md - Secure flows
reference/versions.md - Feature matrix v4.0-7.1
reference/TABLE_OF_CONTENTS.md - Find what you need
See examples.md for 4 complete, working flows:
"markdown": true property to enable formatting**bold**, *italic*, \n for line breaks, • item for listsmarkdown: true, markdown syntax displays as plain textExample:
{
"type": "TextBody",
"text": "**Important:** Please read the following carefully.\n\n• First item\n• Second item",
"markdown": true
}
${screen.FIRST_SCREEN.form.field_name}title property (Business 3.0 requirement)${form.field_name} or ${screen.X.form.field}data_api_version: "3.0" and routing_model to flowdata_exchange action to Footer/DatePicker/selection component__example__ values${data.field_name} in Dropdown, NavigationList, text# Full validation
python scripts/validate_flow.py your-flow.json
# Component-specific validation
python scripts/validate_components.py your-flow.json
Validators check:
${screen.X.form.field} instead of payloadssensitive: truename property (case-sensitive)${form.field} not ${form.Field}errors objectname properties__example__ for all properties${data.field_name}python scripts/validate_flow.py for error detailsSee constraints.md for complete validation rules and common errors.
Currently supports WhatsApp Flow JSON v4.0 - v7.1.
For new flows, use v7.1 with data_api_version: "3.0".
Key features by version:
See versions.md for complete feature matrix and migration guide.
Before deploying flows with sensitive data:
sensitive: trueSee security.md for detailed security practices.
python scripts/validate_flow.pypython scripts/validate_flow.py your-flow.json