WhatsApp Flows

Overview

WhatsApp Flows provide native UI components for building interactive experiences within WhatsApp. Use the Flows API to create, publish, and manage your flows.

List Flows

Retrieve all flows.

GET /api/flows

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`account`	string	Filter by WhatsApp account name
`status`	string	Filter by status (DRAFT, PUBLISHED, DEPRECATED)
`search`	string	Search by flow name (case-insensitive)

Response

{
  "status": "success",
  "data": {
    "flows": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "whatsapp_account": "default_account",
        "meta_flow_id": "123456789012345",
        "name": "Order Form",
        "status": "PUBLISHED",
        "category": "CUSTOMER_SUPPORT",
        "json_version": "6.0",
        "flow_json": {},
        "screens": [
          {
            "id": "WELCOME",
            "title": "Welcome",
            "layout": {
              "type": "SingleColumnLayout",
              "children": [
                {
                  "type": "TextHeading",
                  "text": "Welcome to our store!"
                }
              ]
            }
          }
        ],
        "preview_url": "https://play.google.com/...",
        "has_local_changes": false,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Get Flow

Retrieve a single flow with its full definition.

GET /api/flows/{id}

Response

{
  "status": "success",
  "data": {
    "flow": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "whatsapp_account": "default_account",
      "meta_flow_id": "123456789012345",
      "name": "Order Form",
      "status": "PUBLISHED",
      "category": "CUSTOMER_SUPPORT",
      "json_version": "6.0",
      "flow_json": {},
      "screens": [
        {
          "id": "WELCOME",
          "title": "Welcome",
          "layout": {
            "type": "SingleColumnLayout",
            "children": [
              {
                "type": "TextHeading",
                "text": "Welcome to our store!"
              }
            ]
          }
        }
      ],
      "preview_url": "https://play.google.com/...",
      "has_local_changes": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
}

Create Flow

Create a new WhatsApp Flow locally in DRAFT status.

POST /api/flows

Request Body

Field	Type	Required	Description
`whatsapp_account`	string	Yes	WhatsApp account name
`name`	string	Yes	Flow name
`category`	string	No	Flow category (e.g. `CUSTOMER_SUPPORT`, `UTILITY`)
`json_version`	string	No	Meta JSON format version (default: `6.0`)
`flow_json`	object	No	Optional raw flow JSON mapping
`screens`	array	No	Array of screen objects conforming to the Meta layout

{
  "whatsapp_account": "default_account",
  "name": "Customer Survey",
  "category": "CUSTOMER_SUPPORT",
  "json_version": "6.0",
  "screens": [
    {
      "id": "SURVEY",
      "title": "Quick Survey",
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextHeading",
            "text": "How was your experience?"
          },
          {
            "type": "RadioButtonsGroup",
            "name": "rating",
            "label": "Rating",
            "data-source": [
              {"id": "5", "title": "Excellent"},
              {"id": "4", "title": "Good"},
              {"id": "3", "title": "Average"}
            ]
          },
          {
            "type": "Footer",
            "label": "Submit",
            "on-click-action": {
              "name": "complete",
              "payload": {}
            }
          }
        ]
      }
    }
  ]
}

Response

{
  "status": "success",
  "data": {
    "flow": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "whatsapp_account": "default_account",
      "meta_flow_id": "",
      "name": "Customer Survey",
      "status": "DRAFT",
      "category": "CUSTOMER_SUPPORT",
      "json_version": "6.0",
      "screens": [],
      "preview_url": "",
      "has_local_changes": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
}

Update Flow

Update a flow’s local definition.

PUT /api/flows/{id}

Request Body

Same structure as Create Flow (excluding whatsapp_account). Only fields provided will be updated.

Delete Flow

Delete a flow (soft delete).

DELETE /api/flows/{id}

Response

{
  "status": "success",
  "data": {
    "message": "Flow deleted successfully"
  }
}

Save to Meta

Push the flow definition and layout schema to Meta’s WhatsApp Business API. If the flow doesn’t exist on Meta, it will be created first. The status remains DRAFT on Meta.

POST /api/flows/{id}/save-to-meta

Response

{
  "status": "success",
  "data": {
    "flow": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "meta_flow_id": "123456789012345",
      "status": "DRAFT",
      "has_local_changes": false
    },
    "message": "Flow saved to Meta successfully"
  }
}

Publish Flow

Publish the flow to make it live and active for sending to users.

POST /api/flows/{id}/publish

Response

{
  "status": "success",
  "data": {
    "flow": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "PUBLISHED"
    },
    "message": "Flow published successfully"
  }
}

Deprecate Flow

Deprecate a published flow on Meta and locally. Deprecated flows cannot be edited or sent anymore.

POST /api/flows/{id}/deprecate

Response

{
  "status": "success",
  "data": {
    "flow": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "DEPRECATED"
    },
    "message": "Flow deprecated successfully"
  }
}

Duplicate Flow

Create a copy of an existing flow as a new DRAFT. This is useful for editing published flows (since published flows cannot be directly edited, you can duplicate, make changes, and publish the copy).

POST /api/flows/{id}/duplicate

Response

{
  "status": "success",
  "data": {
    "flow": {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Survey (Copy)",
      "status": "DRAFT"
    },
    "message": "Flow duplicated successfully. You can now edit and publish the new flow."
  }
}

Sync Flows

Sync WhatsApp Flows from Meta’s API for a specific WhatsApp account.

POST /api/flows/sync

Request Body

{
  "whatsapp_account": "default_account"
}

Response

{
  "status": "success",
  "data": {
    "message": "Flows synced successfully",
    "synced": 5,
    "created": 1,
    "updated": 2
  }
}

Flow Status Lifecycle

Status	Description
`DRAFT`	Flow is being designed, not yet available
`PUBLISHED`	Flow is live and can be sent to users
`DEPRECATED`	Flow has been retired