Flows API

The Flows API is a Graph API that enables you to perform a variety of operations with Flows.

Postman Collection

You can use the Flows API postman collection to make API requests and generate code in different languages.

Troubleshooting

See the troubleshooting section for the help with debugging API issues.

Variables Required for API Calls

The following variables are required in these API calls.

API Requests

Creating a Flow

New Flows are created in DRAFT status. You can then make changes to the Flow by uploading an updated JSON file.

Sample Request

curl -X POST '{BASE-URL}/{WABA-ID}/flows' \
--header 'Authorization: Bearer {ACCESS-TOKEN}' \
--header "Content-Type: application/json" \
--data '{
  "name": "My first flow",
  "categories": [ "APPOINTMENT_BOOKING" ]
}'

Sample Response

{
  "id": "<Flow-ID>"
}

Updating Flow's Metadata

After you have created your Flow, you can update the name or categories using the update request.

Sample Request

curl -X POST '{BASE-URL}/{FLOW-ID}' \
--header 'Authorization: Bearer {ACCESS-TOKEN}' \
--header "Content-Type: application/json" \
--data '{
  "name": "New flow name"
}'

Sample Response

{
  "success": true,
}

Updating a Flow's Flow JSON

To update Flow JSON for a specified Flow, use this request. Note that the file must be attached as form-data.

Sample Request

curl -X POST '{BASE-URL}/{FLOW_ID}/assets' \
--header 'Authorization: Bearer {ACCESS-TOKEN}' \
--form 'file=@"/path/to/file";type=application/json' \
--form 'name="flow.json"' \
--form 'asset_type="FLOW_JSON"' # file must be attached as form-data

Sample Response

Every update request will return validation errors in the Flow JSON, if any.

{
  "success": true,
  "validation_errors": [
    {
      "error": "INVALID_PROPERTY",
      "error_type": "JSON_SCHEMA_ERROR",
      "message": "The property \"initial-text\" cannot be specified at \"$root/screens/0/layout/children/2/children/0\".",
      "line_start": 46,
      "line_end": 46,
      "column_start": 17,
      "column_end": 30
    }
  ]
}

Visualizing and interacting with your Flow using the Web Preview

In order to visualize the Flows created, you can generate a web preview URL with this request. The preview URL is public and can be shared with different stakeholders to visualize the Flow. You can also interact with it in a similar way users will interact on their phones adding the URL parameters described in the table below.

Sample Request

curl '{BASE-URL}/{FLOW-ID}?fields=preview.invalidate(false)' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Sample Response

{
  "preview": {
    "preview_url": "https://business.facebook.com/wa/manage/flows/550.../preview/?token=b9d6....",
    "expires_at": "2023-05-21T11:18:09+0000"
  },
  "id": "flow-1"
}

The preview_url can also be embedded as an iframe into an existing website using the following code (replace url with the one returned by the API):

<iframe src="https://business.facebook.com/wa/manage/flows/550.../preview/?token=b9d6...." width="430" height="800" ></iframe>

The following parameters can be added to the generated URL to configure the interactive Web Preview:

Sample URL

https://business.facebook.com/wa/manage/flows/550.../preview/?token=b9d6...&interactive=true&flow_action=navigate&flow_action_payload=%7B%22screen%22%3A%22FIRST_SCREEN%22%2C%22data%22%3A%7B%22screen_heading%22%3A%22hello%20world%22%7D%7D&debug=true

Deleting a Flow

While a Flow is in DRAFT status, it can be deleted. Use this request for that purpose.

Sample Request

curl -X DELETE '{BASE-URL}/{FLOW-ID}' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Sample Response

{
  "success": true,
}

Retrieving a List of Flows

To retrieve a list of Flows under a WhatsApp Business Account (WABA), use the following request.

Sample Request

curl '{BASE-URL}/{WABA-ID}/flows' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Sample Response

{
    "data": [
    {
        "id": "flow-1",
        "name": "flow 1",
        "status": "DRAFT",
        "categories": [ "CONTACT_US" ],
        "validation_errors": []
    },
    {
        "id": "flow-2",
        "name": "flow 2",
        "status": "PUBLISHED",
        "categories": [ "SURVEY" ],
        "validation_errors": []
    },
    {
        "id": "flow-3",
        "name": "flow 3",
        "status": "DRAFT",
        "categories": [ "LEAD_GENERATION" ],
        "validation_errors": []
    }
    ],
    "paging": {
        "cursors": {
            "before": "QVFI...",
            "after": "QVFI..."
        }
    }
}

Retrieving Flow Details

This request will return a single Flow's details. By default it will return the fields id,name, status, categories, validation_errors. You can request other fields by using the fields param in the request. The request example below includes all possible fields.

Sample Request

curl '{BASE-URL}/{FLOW-ID}?fields=id,name,categories,preview,status,validation_errors,json_version,data_api_version,endpoint_uri,whatsapp_business_account,application,health_status' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

To check that a flow can be used with a specific phone number, you can use the optional health_status.phone_number(PHONE_NUMBER_ID) parameter.

Sample Response

{
  "id": "<Flow-ID>",
  "name": "<Flow-Name>",
  "status": "DRAFT",
  "categories": [ "LEAD_GENERATION" ],
  "validation_errors": [],
  "json_version": "3.0",
  "data_api_version": "3.0",
  "endpoint_uri": "https://example.com",
  "preview": {
    "preview_url": "https://business.facebook.com/wa/manage/flows/55000..../preview/?token=b9d6.....",
    "expires_at": "2023-05-21T11:18:09+0000"
  },
  "whatsapp_business_account": {
    ...
  },
  "application": {
    ...
  },
  "health_status": {
    "can_send_message": "BLOCKED",
    "entities": [
      {
        "entity_type": "FLOW",
        "id": "<Flow-ID>",
        "can_send_message": "BLOCKED",
        "errors": [
          {
            "error_code": 131000,
            "error_description": "endpoint_uri: You need to set the endpoint URI before you can send or publish a flow.",
            "possible_solution": "https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson#top-level-flow-json-properties"
          },
          {
            "error_code": 131000,
            "error_description": "app_check: You need to connect a Meta app to the flow before you can send or publish it.",
            "possible_solution": "https://developers.facebook.com/docs/development/create-an-app"
          }
        ]
      },
      {
        "entity_type": "WABA",
        "id": "<WABA-ID>",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "BUSINESS",
        "id": "<Business-ID>",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "APP",
        "id": "<App-ID>",
        "can_send_message": "LIMITED",
        "additional_info": [
          "Your app is not subscribed to the message webhook. This means you will not receive any messages sent to your phone number."
        ]
      }
    ]
  }
}

Retrieving a Flow's List of Assets

Returns all assets attached to a specified Flow.

Sample Request

curl '{BASE-URL}/{FLOW-ID}/assets' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Sample Response

{
  "data": [
    {
      "name": "flow.json",
      "asset_type": "FLOW_JSON",
      "download_url": "https://scontent.xx.fbcdn.net/m1/v/t0.57323-24/An_Hq0jnfJ..."
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIU...",
      "after": "QVFIU..."
    }
  }
}

Publishing a Flow

This request updates the status of the Flow to "PUBLISHED". You can either edit this flow in the future and turn it back to the "DRAFT" state, or create a new flow by specifying the existing Flow ID as the clone_flow_id parameter. For more details, visit the Lifecycle of a Flow page.

You can publish your Flow once you have ensured that:

• Your business is verified and maintains a high message quality.

• All validation errors and publishing checks have been resolved.
• The Flow meets the design principles of WhatsApp Flows
• The Flow complies with WhatsApp Terms of Service, the WhatsApp Business Messaging Policy and, if applicable, the WhatsApp Commerce Policy

Sample Request

curl -X POST '{BASE-URL}/{FLOW-ID}/publish' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Sample Response

{
  "success": true
}

Deprecating a Flow

Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated.

Sample Request

curl -X POST '{BASE-URL}/{FLOW-ID}/deprecate' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Sample Response

{
  "success": true,
}

Migrate Flows

Migrate Flows from one WhatsApp Business Account (WABA) to another. Migration doesn't move the source Flows, it creates copies of them with the same names in the destination WABA.

Notes:

• You can specify specific Flow names to migrate, or choose to migrate all Flows in source WABA.
• Flows can only be migrated between WABAs owned by the same Meta business.
• If a Flow exists with the same name in the destination WABA, it will be skipped and the API will return an error message for that Flow. Other Flows in the same request will be copied.
• The migrated Flow will be published if the original Flow is published, otherwise it will be in draft state.
• New Flows under destination WABA will have new Flow IDs.

Request syntax

curl -X POST '{BASE-URL}/<DESTINATION_WABA_ID>/migrate_flows?source_waba_id=<SOURCE_WABA_ID>
&source_flow_names=<SOURCE_FLOW_NAMES>' \
--header 'Authorization: Bearer {ACCESS-TOKEN}'

Parameters

Response

{
  "migrated_flows": [
    {
      "source_name": "appointment-booking",
      "source_id": "1234",
      "migrated_id": "5678"
    }
  ],
  "failed_flows": [
    {
      "source_name": "lead-gen",
      "error_code": "4233041",
      "error_message": "Flows Migration Error: Flow with the same name exists in destination WABA."
    }
  ]
}

Troubleshooting