Manage WhatsApp Flows

​

What it is

​

Before you begin

• Connect the WABA that will own the Flow.
• Design the screens and data model in a valid Flow JSON document.
• Decide whether the Flow needs a data endpoint.
• Choose categories that describe the Flow use case.
• Keep new work in DRAFT until validation and preview are complete.

​

How it works

1. Create a Flow with metadata and, optionally, its JSON structure.
2. Retrieve the Flow and fix every validation error.
3. Update metadata or upload a revised Flow JSON file.
4. Generate a public preview URL for stakeholder testing.
5. Publish the Flow when it is ready for messages.
6. Deprecate a published Flow when it should no longer be used.

​

Request

​

Create a Flow

curl --request POST https://api.ycloud.com/v2/whatsapp/flows \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wabaId": "WABA_ID",
    "name": "Appointment booking",
    "categories": ["APPOINTMENT_BOOKING"],
    "flowJson": "{\"version\":\"5.0\",\"screens\":[]}",
    "publish": false,
    "endpointUri": "https://example.com/whatsapp/flow"
  }'

​

Update the Flow structure

curl --request PATCH \
  https://api.ycloud.com/v2/whatsapp/flows/FLOW_ID/assets \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "flowJson=@./flow.json;type=application/json"

​

Preview and publish

​

Response

{
  "id": "FLOW_ID",
  "success": true
}

{
  "id": "FLOW_ID",
  "name": "Appointment booking",
  "status": "DRAFT",
  "categories": ["APPOINTMENT_BOOKING"],
  "validationErrors": []
}

​

Flow lifecycle

​

Limits and troubleshooting

• Treat every validation error pointer as a location in the Flow JSON to fix.
• Preview URLs are public; do not include production secrets or sensitive test data.
• Publishing is a lifecycle boundary. Confirm content and endpoint behavior first.
• Only delete a Flow when its current state allows deletion.
• Version Flow JSON and endpoint behavior together when they exchange data.