Create and update Flows

Last update: 6 hours ago by Irais Aguirre

Create a WhatsApp Flow and upload or update its JSON definition and metadata.

Integration summary
Base URL: https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services
Token: admin token, in the Authorization: Bearer {{admin-token}} header (how to generate it)
Endpoints on this page:
POST /v1/flows/{{waba_id}}: Create Flow
POST /v1/flows/{{waba_id}}/{{flow_id}}/assets: Upload Flow JSON
PUT /v1/flows/{{waba_id}}/{{flow_id}}: Update metadata

Create Flow

Request

Create Flow request:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/flows/{{waba_id}}
Method	POST
Type	application/json

Headers

Create Flow headers:

Name	Description	Type	Requirements
Content-Type	application/json	String	Required
Authorization	Admin token. See Generate authentication token.	String	Required

Parameters

Create Flow parameters:

Name	Description	Type	Requirements
waba_id	WhatsApp Business Account ID.	String	Required

Body

Create Flow body fields:

Name	Description	Type	Requirements
name	Flow name.	String	Required
categories	List of categories for the Flow. You can assign multiple values, but at least one is required: SIGN_UP SIGN_IN APPOINTMENT_BOOKING LEAD_GENERATION CONTACT_US CUSTOMER_SUPPORT SURVEY OTHER	Array	Required
clone_flow_id	ID of the source Flow to clone. You must have permission to access the specified Flow.	String	Optional
endpoint_uri	URL of the WA Flow Endpoint.	String	Optional

Example

Complete Create Flow example:

curl --location 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/flows/{{waba_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{admin-token}}' \
--data '{
    "name": "New flow name",
    "categories": [ "CUSTOMER_SUPPORT" ],
    "clone_flow_id": "flow-1",
    "endpoint_uri": "https://example.com"
}'

Response

Create Flow response:

Name	Description	Type
id	Flow ID.	String

{
    "id": "flow-1"
}

Upload Flow JSON

Request

Upload Flow JSON request:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/flows/{{waba_id}}/{{flow_id}}/assets
Method	POST
Type	multipart/form-data

Headers

Upload Flow JSON headers:

Name	Description	Type	Requirements
Authorization	Admin token. See Generate authentication token.	String	Required

Parameters

Upload Flow JSON parameters:

Name	Description	Type	Requirements
waba_id	WhatsApp Business Account ID.	String	Required
flow_id	Flow ID returned by Create Flow.	String	Required

Body

Upload Flow JSON body fields:

Name	Description	Type	Requirements
file	File with the Flow JSON content. The file must have a `.json` extension. For the components Meta allows when building the JSON, see Flow JSON. We recommend using version 7.0 or later.	File	Required. Only `.json` files are accepted; other extensions are rejected. Maximum file size: 10 MiB (10,485,760 bytes).

Example

Complete Upload Flow JSON example:

curl --location 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/flows/{{waba_id}}/{{flow_id}}/assets' \
--header 'Authorization: Bearer {{admin-token}}' \
--form 'file=@"/file/path/flows_body.json"'

Response

Upload Flow JSON response:

Name	Description	Type
success	Returns `true` if the Flow JSON was uploaded successfully; otherwise, returns `false`.	Boolean
validation_errors	Object describing any errors found in the Flow JSON. If no errors are found, an empty array is returned.	List of objects

{
    "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
        }
    ]
}

Validation errors object

Name	Description	Type
error	Error name.	String
error_type	Error type.	String
message	Error description.	String
line_start	Line where the error starts.	Integer
line_end	Line where the error ends.	Integer
column_start	Column where the error starts.	Integer
column_end	Column where the error ends.	Integer

For more information about the errors you may get when uploading a Flow JSON file and how to fix them, see Meta's documentation: Static validation errors.

Update metadata

Request

Update metadata request:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/flows/{{waba_id}}/{{flow_id}}
Method	PUT
Type	application/json

Headers

Update metadata headers:

Name	Description	Type	Requirements
Content-Type	application/json	String	Required
Authorization	Admin token. See Generate authentication token.	String	Required

Parameters

Update metadata parameters:

Name	Description	Type	Requirements
waba_id	WhatsApp Business Account ID.	String	Required
flow_id	Flow ID returned by Create Flow.	String	Required

Body

Update metadata body fields:

Name	Description	Type	Requirements
name	Flow name.	String	Required
categories	List of categories for the Flow. You can assign multiple values, but at least one is required: SIGN_UP SIGN_IN APPOINTMENT_BOOKING LEAD_GENERATION CONTACT_US CUSTOMER_SUPPORT SURVEY OTHER	Array	Required
endpoint_uri	URL of the WA Flow Endpoint.	String	Optional

Note: clone_flow_id is a Create-only field. If sent on this Update endpoint, the request is rejected.

Example

Complete Update metadata example:

curl --location --request PUT 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/flows/{{waba_id}}/{{flow_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{admin-token}}' \
--data '{
    "name": "New flow name",
    "categories": [ "CUSTOMER_SUPPORT" ],
    "endpoint_uri": "https://example.com"
}'

Response

Update metadata response:

Name	Description	Type
success	Returns `true` if a property was updated successfully; otherwise, returns `false`.	Boolean

{
    "success": true
}

WhatsApp — Previous

WhatsApp Flows

Query Flows