> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage WhatsApp Flows

> Create, validate, preview, publish, and deprecate structured WhatsApp experiences.

## What it is

WhatsApp Flows are multi-screen experiences that run inside WhatsApp. Use them
for structured tasks such as sign-up, appointment booking, lead collection,
feedback, or product configuration.

## 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.

Draft Flows can be edited or deleted. Published Flows have stricter lifecycle
rules, so test before publishing.

## Request

### Create a Flow

`POST /whatsapp/flows`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

`PATCH /whatsapp/flows/{flowId}/assets`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

Generate a preview with `GET /whatsapp/flows/{flowId}/preview`, then publish
with `POST /whatsapp/flows/{flowId}/publish`.

## Response

Creation returns the new Flow ID and operation result.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "FLOW_ID",
  "success": true
}
```

Retrieval returns the Flow lifecycle state and validation details.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "FLOW_ID",
  "name": "Appointment booking",
  "status": "DRAFT",
  "categories": ["APPOINTMENT_BOOKING"],
  "validationErrors": []
}
```

## Flow lifecycle

| State | Meaning |
| - | - |
| `DRAFT` | The Flow can be edited, validated, previewed, or deleted. |
| `PUBLISHED` | The Flow can be referenced by messages. |
| `DEPRECATED` | The Flow should no longer be used for new interactions. |
| `BLOCKED` or `THROTTLED` | Meta has restricted the Flow; inspect status details. |

Use `whatsapp.flow.status_change` webhooks to process asynchronous lifecycle
updates.

## 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.

<CardGroup cols={2}>
  <Card title="Create a Flow API" icon="diagram-project" href="/api-reference/whatsapp-flows/create-a-flow">
    Inspect metadata, JSON, clone, and publish options.
  </Card>

  <Card title="Flow webhooks" icon="webhook" href="/en/api-reference/guides/examples/webhook-examples/whatsapp-flow-webhook-examples">
    Handle Flow status changes.
  </Card>
</CardGroup>

For health checks, data exchange, validation, and completion responses, follow
[Implement a WhatsApp Flow endpoint](/en/api-reference/guides/whatsapp-platform/implement-a-whatsapp-flow-endpoint).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.