# WhatsApp Flow builder

> Create, import, validate, and preview project-scoped WhatsApp Flows in the Polymorfa Console.

Use **Flows** in a project to author a multi-screen WhatsApp experience. Flow drafts are shared project resources, so Cloud API and linked-device projects use the same editor and Flow identifier.

The Flows table lists each draft's name, screen count, version, and last update.
Open a column heading to sort or filter by that property. Drag a heading edge
to resize the column. Right-click a row to open the same actions shown under
**More**.

## Create a Flow

1. Open a project and select **Flows**.
2. Select **New Flow**.
3. Rename the draft, add screens, and add components to each screen.
4. Select a screen in the **Screens** list to edit it or inspect its destinations.

A Flow opens on the **Editor** tab. On narrower screens, switch between **Screens**, **Edit** and **Preview** at the top of the tab.

The Console saves a new draft as soon as the editor opens. Later edits save after a short delay. **Saved** confirms that the displayed version reached Polymorfa. **Conflict**, with the message "This changed since you opened it.", means someone saved a newer version. The Console stops saving your edits; select **Export** to keep them, then **Refresh** to load the latest version.

Drafts accept incomplete Flow documents. The checks status in the summary reports duplicate screen IDs, missing route destinations, duplicate field names, terminal screens that navigate, and resource-limit failures before upload.

Deleting a Flow from the Flows table removes the project draft. Copies already uploaded to WhatsApp are not deleted.

## Publish to WhatsApp

Open the **Publish** tab of a saved Flow. It lists each number in the project with the Flow's WhatsApp status on that number (**Draft**, **Published**, **Deprecated**, **Throttled**, **Blocked** or **Not uploaded**), the result of the last upload, and the WhatsApp Flow ID to use as `flow_id` when sending.

- **Upload** sends the saved draft to the number. A first upload, or one after deprecation, asks for a category. WhatsApp checks the Flow again on upload and lists any validation errors under the number.
- **Publish** is available for an uploaded draft without validation errors. A published Flow cannot be changed or deleted.
- **Deprecate** stops a published Flow from being sent. This cannot be undone.
- **Delete from number** removes an unpublished draft from the number. Your saved draft stays.
- **Sync** reads the current status from WhatsApp. Use it when the Console shows that WhatsApp has not confirmed the last change.

Save your changes before uploading or publishing. Upload and Publish stay unavailable while an edit is saving, after a save fails or conflicts, and while the Flow JSON is invalid.

## Use the recipient preview

The preview renders the selected Flow screen inside a WhatsApp conversation. You can fill fields, select choices, follow local screen navigation, and test completion actions. Preview interactions remain in your browser and do not send messages, open embedded links, or persist submitted form data.

> **Warning**
>
> **Local preview** is an authoring aid. Meta validates the complete Flow schema
> and provides its own expiring hosted preview after a Flow is uploaded to a
> compatible Cloud API number. Use that hosted preview as the final rendering
> check before publication.

The local preview renders headings, body text, captions, text inputs, text areas, dropdowns, radio and checkbox groups, date pickers, opt-ins, embedded links, forms, and footer actions. A newer or unsupported component appears as a diagnostic card and remains unchanged in the saved JSON.

## Edit or move Flow JSON

Select **JSON** to edit the complete document. Invalid JSON remains in the editor and is not applied to the visual preview. While it is invalid, the summary shows **Invalid JSON**, the last valid version stays saved, and **Export** downloads the text as you typed it. Polymorfa preserves unknown fields and component objects instead of removing data it does not understand.

Use **Import** to replace the working document with a `.json` file. Use **Export** before a large edit, when resolving a revision conflict, or when moving a draft between systems.

Flow drafts have these authoring limits:

| Limit | Value |
| --- | ---: |
| JSON document | 2 MB |
| Screens | 50 |
| Components | 1,000 |
| JSON nesting depth | 32 |

The Flow version remains an editable string. Polymorfa does not rewrite an imported document to a presumed latest Meta version.

## Manage drafts in code

Flow drafts are project resources. Listing and reading need `sessions:read`;
creating, updating and deleting need `sessions:manage`. A project token
reaches only its own project.

**API:**

Use [List flow drafts](https://docs.polymorfa.com/api/flows/list-flow-drafts),
[Get flow](https://docs.polymorfa.com/api/flows/get-flow),
[Create flow draft](https://docs.polymorfa.com/api/flows/create-flow-draft),
[Update flow](https://docs.polymorfa.com/api/flows/update-flow) and
[Delete flow](https://docs.polymorfa.com/api/flows/delete-flow) under `/platform/flows`.

```bash cURL
curl "https://api.polymorfa.com/platform/flows?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const drafts = await project.flows.list();
for (const draft of drafts.data) console.log(draft.id, draft.name, draft.status);

const created = await project.flows.create({
  name: "Booking",
  definition: { version: "7.0", screens: [] },
});

const current = await project.flows.retrieve(created.data.id);
if (current.data) {
  await project.flows.update(created.data.id, {
    expectedUpdatedAt: current.data.updatedAt,
    name: "Booking v2",
  });
}

await project.flows.delete(created.data.id);
```

```bash Graph API
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/flows" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

**Graph API:** Meta Cloud API Numbers: Partly supported. Linked Devices Numbers: Not supported.

The Graph API works with a WhatsApp Business Account's Flows at Meta, not
project drafts. [List WABA flows](https://docs.polymorfa.com/api/graph/flows/list-waba-flows)
needs `sessions:read`, and [Create WABA flow](https://docs.polymorfa.com/api/graph/flows/create-waba-flow)
takes Meta's Flow body and needs `messages:write`. Updating, publishing and
deleting a Flow are not offered. Linked Devices Numbers return capability
error `131026`.

An update sends `expectedUpdatedAt`, the draft's `updatedAt` in Unix
milliseconds from your last read. If someone saved the draft since then, the
update is refused; read it again before you retry.

*TypeScript:*

Use a project client, such as `platform.project("<project-id>")`, or a client
created with a project token. Flow methods return the draft itself in
`response.data`:

`list` returns `FlowSummary` items. `retrieve` returns a `FlowDraft`, which
adds the `definition`, or `null` when no draft has that ID. `update` fails if
someone changed the draft after the `updatedAt` you pass.

## Cloud API and linked-device projects

Authoring, draft storage, import, export, validation, and local preview behave the same for both connection types.

A Cloud API number can link the project draft to a Meta Flow asset for hosted preview and lifecycle operations. Linked-device connections can send an already published Flow through the Messaging API, but the linked-device protocol does not provide Meta Flow asset upload or publication. The Console labels unavailable lifecycle actions instead of treating a local draft as published.

To send a published Flow, use `content.flow` in [Send messages](https://docs.polymorfa.com/messaging/send#interactive-messages).

## See also

- [Send messages](https://docs.polymorfa.com/messaging/send)
- [Flows API reference](https://docs.polymorfa.com/api/flows/list-flow-drafts)
