Messaging

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 sends it with a text and a button, then saves Camille's answers to the run or to her attributes; her conversation 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 describes their parameters, payloads, and errors.

  • POST

    createWhatsAppFlow

    Create a WhatsApp Flow

    /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows
  • PUT

    replaceWhatsAppFlowDraft

    Replace the draft of a WhatsApp Flow

    /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}/draft
  • POST

    publishWhatsAppFlow

    Publish a WhatsApp Flow

    /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}/publish
  • GET

    getWhatsAppFlow

    Get a WhatsApp Flow

    /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}
  • GET

    listWhatsAppFlows

    List WhatsApp Flows

    /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows
  • DELETE

    deleteWhatsAppFlow

    Delete a WhatsApp Flow

    /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/flows/{flowId}