Skip to main content

Documentation Index

Fetch the complete documentation index at: https://howto.paigeme.dev/llms.txt

Use this file to discover all available pages before exploring further.

WhatsApp Flows let you collect structured information from users inside the WhatsApp chat — without sending them to a website or asking them to reply to a series of messages. A flow opens as a sequence of screens with inputs, dropdowns, date pickers, and selection controls. When the user submits the final screen, the data is delivered back to your bot as a single webhook event. Flows are ideal for appointment booking, lead capture, surveys, sign-up forms, customer support intake, and any other structured data collection that would otherwise require multiple back-and-forth messages.

​
How flows work in Paige

Each flow is defined as a JSON file stored in your project at flows/{name}.json. Paige’s AI agent generates and manages this JSON for you — you describe what you want and the agent creates the correct structure, validates it against Meta’s schema, and uploads it to your WhatsApp Business Account.

​
Flow lifecycle

1

Generate the flow

Ask the AI agent to create a flow. Describe the screens, inputs, and logic you need. The agent writes the JSON, saves it to flows/{name}.json, and uploads it to Meta as a DRAFT.
2

Check for validation errors

After generating, the agent checks the flow against Meta’s API. If there are validation errors, the agent fixes them automatically.
3

Publish the flow

Once the draft looks right, publish it. Published flows can be sent to users. Ask the agent “publish my [flow name] flow” or use the Flows section in your project dashboard.
4

Embed in your bot

Use sendFlow() in your bot code to send the flow to a user. When they submit it, your webhook receives the data and your bot can process it.
When you update a published flow, Meta moves it back to DRAFT status automatically. You need to republish it after any update.

​
Creating a flow with the AI agent

Describe the flow you want in plain language. Be specific about the screens, the type of inputs, and any logic between screens. Example prompts:
“Create a 3-screen appointment booking flow. The first screen asks the user to select a service from a dropdown. The second screen has a date picker and a time slot dropdown. The third screen shows a summary and a confirm button.”
“Build a lead capture flow with two screens. The first screen collects the user’s name and email. The second screen asks how they heard about us using radio buttons, then has a submit button.”
“Create a customer support intake flow that collects a subject, a description (text input), and an urgency level (dropdown: Low, Medium, High).”
The agent picks the right components for each screen based on your description.

​
Flow components

WhatsApp Flows support a specific set of UI components. The agent knows which components are valid and in what contexts they can be used.
A bold heading displayed at the top of a screen or section. Use it to label each screen clearly.
{ "type": "TextHeading", "text": "Book your appointment" }
Regular body text for instructions or descriptions. Supports basic formatting.
{ "type": "TextBody", "text": "Fill in your details below and we'll confirm your slot." }
A single-line or multi-line text field. Used for names, email addresses, notes, or any free-text input.
{
  "type": "TextInput",
  "name": "full_name",
  "label": "Full name",
  "required": true
}
A native date selector. Returns the selected date as a string in ISO format.
{
  "type": "DatePicker",
  "name": "appointment_date",
  "label": "Preferred date",
  "required": true
}

​
Updating an existing flow

To modify an existing flow, ask the agent to update it — do not edit the flow JSON file directly.
“Update the booking flow: replace the time slot dropdown with a list of radio buttons.”
“Fix the appointment flow — add a confirmation screen at the end that shows the selected date and service before submitting.”
The agent reads the current flow JSON, applies your changes, re-validates the structure, and re-uploads the updated draft to Meta.
Never edit a flow’s JSON file manually. The flows sub-agent enforces Meta’s schema and validation rules. Direct file edits will likely produce invalid JSON that cannot be uploaded.

​
Publishing and deprecating a flow

Publish a draft flow to make it available to send to users.From the AI agent:
“Publish my appointment_booking flow.”
From the dashboard: navigate to the Flows section, find the flow, and click Publish.
You can only publish flows that have no validation errors. If publishing fails, ask the agent to check the flow for errors.

​
Receiving flow submissions in your bot

When a user completes and submits a flow, your webhook receives an interactive message with message.interactive.nfm_reply. The submitted form data is nested inside that object. 
if (incoming.type === "interactive" && incoming.interactive?.nfm_reply) {
  const flowData = JSON.parse(incoming.interactive.nfm_reply.response_json);

  // Access submitted fields by the name you defined in the flow
  const fullName = flowData.full_name;
  const service = flowData.service;
  const appointmentDate = flowData.appointment_date;

  // Save to your database and send a confirmation
  await db.insertRow("bookings", { name: fullName, service, date: appointmentDate, phone: from });
  await sendText(conversationId, from, `Thanks ${fullName}, your ${service} appointment on ${appointmentDate} is confirmed.`);
}

​
Pre-built flow templates

Paige provides pre-built flow templates for common use cases to help you get started quickly. See Flow Templates for the full list.