Send WhatsApp Flow Card

The Send WhatsApp Flow card initiates a native, interactive Meta Flow form within the customer's WhatsApp chat without redirecting them to an external web browser.

Technical Overview

Card ID: send_whatsapp_flow
Category: Send Message / Interactive
Meta API Support: WhatsApp Cloud API v21.0+
Security: AES-GCM Encrypted Form Data Transfer

sequenceDiagram
    autonumber
    actor Customer as Patient / Customer
    participant WA as WhatsApp App
    participant Meta as Meta Graph API
    participant Engine as SMSPort Bot Engine
    participant EMR as Hospital / CRM Database

    Engine->>Meta: POST /messages (interactive flow payload)
    Meta->>WA: Renders native interactive Flow button
    Customer->>WA: Fills in multi-screen medical form & submits
    WA->>Meta: Transmits encrypted envelope
    Meta->>Engine: POST /api/v1/whatsapp/flows webhook
    Engine->>Engine: Decrypts AES-GCM payload with RSA private key
    Engine->>EMR: Stores responses & updates patient profile
    Engine->>WA: Sends confirmation card

Configuration Parameters

Parameter	Type	Required	Description
`flow_id`	`string`	Yes	The numeric ID of the published Meta Flow (e.g. `849302194829`).
`screen_id`	`string`	Yes	Initial screen identifier defined in Flow JSON (e.g. `SCREEN_PERSONAL_INFO`).
`header_text`	`string`	No	Optional bold header displayed above the message body.
`body_text`	`string`	Yes	Contextual prompt inviting the customer to open the form.
`cta_label`	`string`	Yes	Button label (max 20 chars, e.g. `Book Appointment`, `Fill Intake`).
`initial_data`	`json`	No	Dynamic key-value payload pre-filling form fields via variable tags.

Prerequisites & Meta Requirements

[!IMPORTANT]

Flow Status: The Flow must have status PUBLISHED in your Meta WhatsApp Manager. Draft or Deprecated flows will return code 131009.

24-Hour Messaging Window: Free-form interactive flow messages can only be dispatched within an active 24-hour customer service window. For outbound initiation, the flow must be wrapped in an approved utility template.

Data Encryption: If the flow handles sensitive patient data, ensure your workspace private key is configured under Modular Integrations > Meta Cloud API.

Output Data Schema (Codex)

When the user submits the form, subsequent cards can access answers using dot notation:

{
  "flow_token": "tok_94829104",
  "screen_id": "SCREEN_PERSONAL_INFO",
  "responses": {
    "patient_name": "Sarah Connor",
    "blood_group": "O+",
    "preferred_slot": "10:30 AM",
    "symptoms": "Fever, headache"
  },
  "completed_at": "2026-09-18T05:37:10Z"
}

Example Variable Access

{{last_node.responses.patient_name}}
{{last_node.responses.preferred_slot}}