WhatsApp Flow Components Reference

Meta WhatsApp Flows supports 23 distinct UI components categorized into text blocks, form inputs, selection controls, date pickers, media containers, navigation menus, and conditional containers.

Below is the complete reference dictionary, property requirements, and version compatibility matrix.

1. Component Availability Matrix

2. Text & Typography Components

`TextHeading`, `TextSubheading`, `TextBody`, `TextCaption`

{
  "type": "TextHeading",
  "text": "Book Your Consultation"
},
{
  "type": "TextBody",
  "text": "Please choose your preferred branch and consultation mode.",
  "markdown": true
}

`RichText` (Flow 5.1+)

Accepts an array of markdown strings formatted with headers, bold text, and bullet lists:

{
  "type": "RichText",
  "text": [
    "# Terms of Service",
    "Please read these conditions carefully before submitting:",
    "- All bookings require 24 hours cancellation notice.",
    "- Consultation fees are charged upon appointment arrival."
  ]
}

3. Interactive Input Fields

`TextInput`

{
  "type": "TextInput",
  "name": "patient_email",
  "label": "Email address",
  "input-type": "email",
  "required": true,
  "helper-text": "We will send your confirmation slip here"
}

Supported input-type values: "text", "number", "email", "phone", "password". Regex patterns can be provided via "pattern": "^[0-9]{10}$".

`TextArea`

{
  "type": "TextArea",
  "name": "symptoms_description",
  "label": "Reason for visit",
  "max-length": "500",
  "required": false
}

4. Selection Components

`Dropdown`

In SMSPort's simulator and client devices, Dropdown opens a native full-screen bottom sheet with live search filtering:

{
  "type": "Dropdown",
  "name": "preferred_branch",
  "label": "Select medical centre",
  "data-source": "${data.branch_list}",
  "required": true
}

`RadioButtonsGroup` & `CheckboxGroup`

{
  "type": "RadioButtonsGroup",
  "name": "consultation_type",
  "label": "Choose appointment type",
  "data-source": [
    { "id": "in_person", "title": "In-Person Clinic Visit", "description": "Meet with doctor at clinic" },
    { "id": "video", "title": "Video Tele-Consultation", "description": "15-minute secure video call" }
  ],
  "required": true
}

`ChipsSelector` (Flow 6.3+)

{
  "type": "ChipsSelector",
  "name": "health_concerns",
  "label": "Select topics",
  "data-source": "${data.concern_chips}",
  "max-selected-items": 3
}

5. Advanced Controls (Meta 6.1+ & 7.1+)

`CalendarPicker` (Flow 6.1+)

Interactive month grid allowing single date or range selection:

{
  "type": "CalendarPicker",
  "name": "appointment_date",
  "label": "Appointment date",
  "mode": "single",
  "min-date": "2026-05-01",
  "max-date": "2026-12-31"
}

`NavigationList` (Flow 6.2+)

Renders row menu items with chevrons (>) that transition directly to sub-screens:

{
  "type": "NavigationList",
  "name": "department_menu",
  "list-items": "${data.departments}",
  "on-click-action": {
    "name": "navigate",
    "next": { "type": "screen", "name": "DOCTOR_SELECTION" },
    "payload": { "dept_id": "${form.department_menu}" }
  }
}

`ImageCarousel` (Flow 7.1+)

Horizontal swipeable gallery with pagination dots and aspect ratio enforcement (1:1, 4:3, 16:9):

{
  "type": "ImageCarousel",
  "aspect-ratio": "16:9",
  "images": "${data.hospital_photos}"
}

6. Media Upload Components (Flow 4.0+)

WhatsApp Flows v4.0+ introduces native file upload components allowing users to capture or attach media within a Flow session.

`PhotoPicker`

Enables users to take a photo using their device camera or select images from their photo gallery:

{
  "type": "PhotoPicker",
  "name": "kyc_selfie",
  "label": "Identity verification selfie",
  "description": "Please take a clear photo of your face in good lighting.",
  "photo-source": "camera",
  "min-uploaded-photos": 1,
  "max-uploaded-photos": 2,
  "max-file-size-kb": 10240
}

Properties:

`DocumentPicker`

Allows users to upload documents (such as PDF files, invoices, contracts, or diagnostic reports):

{
  "type": "DocumentPicker",
  "name": "signed_contract",
  "label": "Upload signed agreement",
  "description": "Attach the signed PDF copy of your agreement.",
  "allowed-mime-types": ["application/pdf"],
  "min-uploaded-documents": 1,
  "max-uploaded-documents": 5,
  "max-file-size-kb": 5120
}

Properties:

Critical Meta Constraints for Media Pickers:

1. Flow JSON Version: Minimum Flow JSON version 4.0 is required.
2. One Media Picker Per Screen: A screen may contain at most one PhotoPicker or one DocumentPicker.
3. Mutual Exclusion: PhotoPicker and DocumentPicker cannot exist together on the same screen.
4. Form init-values Prohibited: Media pickers cannot be pre-populated or referenced in Form init-values.
5. No navigate Action Payloads: Media picker values cannot be forwarded inside navigate action payloads between screens. They can only be submitted to dynamic endpoints via data_exchange or completed via complete action.
6. Encrypted CDN Storage: Files uploaded through WhatsApp Flows are automatically end-to-end encrypted and stored on WhatsApp's MMG CDN. Your endpoint receives download URLs alongside AES-256 decryption metadata.