> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Flows: collect a form's answers on WhatsApp

> Build a WhatsApp form of one or more screens that customers fill in without leaving the chat, and read their typed answers back.

Camille wants to book a repair. Instead of asking her name, the day, and the time one message at a time, the shop sends her a Flow: a button in the chat that opens a form inside WhatsApp. She fills in two screens, taps Book, and the shop receives her answers together.

A Flow belongs to a workspace. Its screens hold texts and inputs, such as a short answer, a choice, a date, or a consent box, and each input stores its answer under its own `field`, such as the day of the visit.

## How does a Flow change once it is sent?

A Flow has a draft that members edit and numbered versions that they publish. Every message carries the latest published version, so editing the draft changes nothing a contact sees until the next publication. A message already sent keeps its version, even once the Flow is deleted, and its answers are read against it, so a field renamed later still reads Camille's earlier answer.

## How does an automation send a Flow?

An `ask_flow` [step](https://heythere.io/docs/concepts/steps) sends it with a text and a button, then saves Camille's answers to the run or to her [attributes](https://heythere.io/docs/concepts/attributes); her [conversation](https://heythere.io/docs/concepts/conversations) shows both. Publishing refuses a step whose Flow has no published version, or lacks a field the step saves.

## Which rules does a Flow follow?

- A Flow holds up to 10 screens, and the button of the last one sends the answers.
- Each `field` is unique across the screens, and each answer has the type of its input: a number for a numeric short answer, a date, a list for a multiple choice, a yes or no for a consent, a text otherwise.
- A Flow may receive variables when it is sent, such as her first name: a text shows one between double braces, and an input may show one first.
- Heythere publishes each version as its own Flow in the sending number's business account when it first sends it, named `heythere-<flow id>-v<version>-copy1`.

## What if a Flow cannot be sent?

A Flow sends nothing until it has a published version. When WhatsApp refuses to publish it in a business account, such as one Meta has not verified, the message is not sent; check the account in WhatsApp Manager.

If someone deprecates that copy in WhatsApp Manager, the next message publishes `-copy2` and goes out through it; a message sent before may no longer open.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `createWhatsAppFlow`: Create a WhatsApp Flow. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows`
- `replaceWhatsAppFlowDraft`: Replace the draft of a WhatsApp Flow. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}/draft`
- `publishWhatsAppFlow`: Publish a WhatsApp Flow. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}/publish`
- `getWhatsAppFlow`: Get a WhatsApp Flow. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}`
- `listWhatsAppFlows`: List WhatsApp Flows. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows`
- `deleteWhatsAppFlow`: Delete a WhatsApp Flow. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}`
