The Flows API is a Graph API that enables you to perform a variety of operations with Flows.
You can use the Flows API postman collection to test API requests and generate code in different languages.
See the troubleshooting section for the help with debugging API issues.
The following variables are required in these API calls.
Key | Value |
---|---|
BASE-URL | Base URL for Facebook Graph API Example: https://graph.facebook.com/v18.0 |
ACCESS-TOKEN | User access token for authentication. This can be retrieved by copying the Temporary access token from your app which expires in 24 hours. Alternatively, you can generate a System User Access Token. |
WABA-ID | This can be retrieved by copying the WhatsApp Business Account ID from your app. |
FLOW-ID | ID of a Flow returned after calling Create 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" ] }'
Parameter | Description | Optional |
---|---|---|
| Flow name | |
| A list of Flow categories. Multiple values are possible, but at least one is required. Choose the values which represent your business use case. The list of values:
| |
| ID of source Flow to clone. You must have permission to access the specified Flow. | ✓ |
| The URL of the WA Flow Endpoint. Starting from Flow JSON version 3.0 this property should be specified only via API. Do not provide this field if you are cloning a Flow with Flow JSON version below 3.0. | ✓ |
Sample Response
{ "id": "<Flow-ID>" }
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" }'
Parameter | Description | Optional |
---|---|---|
| Flow name | ✓ |
| A list of Flow categories. Missing value will keep existing categories. If provided, at least one values is required. | ✓ |
| The URL of the WA Flow Endpoint. Starting from Flow JSON version 3.0 this property should be specified via API or via the Builder UI. Do not provide this field if you are updating a Flow with Flow JSON version below 3.0. | ✓ |
| The ID of the Meta application which will be connected to the Flow. All the flows with endpoints need to have an Application connected to them. | ✓ |
Sample Response
{ "success": true, }
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
Parameter | Description | Optional |
---|---|---|
| Flow asset name. The value must be | |
| Asset type. The value must be | |
| File with the JSON content. The size is limited to 10 MB |
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 } ] }
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.
Web preview URLs are only used to visualize how the screens will look - they will not be interactive. The final screens will render slightly differently for the end user.
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" }
Field | Description |
---|---|
preview_url | Link for the preview page. This link does not require login and can be shared with stakeholders, but the link will expire in 30 days, or if you call the API with |
expires_at | Time when the link will expire and the developer needs to call the API again to get a new link (30 days from link creation). |
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, }
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..." } } }
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' \ --header 'Authorization: Bearer {ACCESS-TOKEN}'
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": { ... } }
Field | Description | Returned by default |
---|---|---|
| The unique ID of the Flow. | ✓ |
| The user-defined name of the Flow which is not visible to users. | ✓ |
|
| ✓ |
| A list of flow categories. | ✓ |
| A list of errors in the Flow. All errors must be fixed before the Flow can be published. | ✓ |
| The version specified by the developer in the Flow JSON asset uploaded. | |
| The version of the Data API specified by the developer in the Flow JSON asset uploaded. Only for Flows with an Endpoint. | |
| [DEPRECATED in API v19.0 ] Use The URL of the WA Flow Endpoint specified by the developer via API or in the Builder UI. | |
| The URL of the WA Flow Endpoint specified by the developer via API or in the Builder UI. | |
| The URL to the web preview page to visualize the flow and its expiry time. | |
| The WhatsApp Business Account which owns the Flow. | |
| The Facebook developer application used to create the Flow initially. |
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..." } } }
This request updates the status of the Flow to "PUBLISHED". This action is not reversible. The Flow and its assets become immutable once published. To update the Flow after that, you must create a new Flow. You specify the existing Flow ID as the clone_flow_id
parameter while creating to copy the existing flow.
You can publish your Flow once you have ensured that:
Sample Request
curl -X POST '{BASE-URL}/{FLOW-ID}/publish' \ --header 'Authorization: Bearer {ACCESS-TOKEN}'
Sample Response
{ "success": true }
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, }
Issue | Potential cause | Steps to resolve |
---|---|---|
Received a permission error while calling the API | Insufficient Permissions | You can check your permissions with the following link (replace WA Business Account ID and Business ID with your values) https://business.facebook.com/settings/whatsapp-business-accounts/{waba-id}?business_id={business-id} To use Flows API you need Message templates (view and manage) and Phone Numbers (view and manage) permissions. |
Incorrect Access Token | Use the Access Token Debugger tool to verify your token permissions https://developers.facebook.com/tools/debug/accesstoken In Scopes field, you should have whatsapp_business_management, whatsapp_business_messaging. And under Granular Scopes section you should see your WABA Id under both whatsapp_business_management and whatsapp_business_messaging After you verify access token, please try to make basic request with the the token, like | |
Invalid request syntax | Use the Postman Collection to make the same request. |