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

> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md

# WhatsApp Flows

> Send customers a form inside WhatsApp from a Ringg AI agent, like a booking, a lead form or a survey, and get their answers back as the next chat message.

export const RelatedTopics = ({items}) => <div className="not-prose mt-12">
    <div className="text-sm font-medium text-gray-500 dark:text-zinc-400 mb-3">Related topics</div>
    <div className="flex flex-col gap-2.5">
      {items.map(([title, href]) => <a key={href} href={href} className="flex items-center gap-2.5 text-sm text-gray-700 hover:text-gray-950 dark:text-zinc-300 dark:hover:text-white">
          <Icon icon="file-text" size={16} color="currentColor" />
          {title}
        </a>)}
    </div>
  </div>;

A **WhatsApp Flow** is a form that opens inside WhatsApp. The customer taps a button in the chat, fills in a few screens (text fields, dropdowns, dates, checkboxes) and submits. Their answers come straight back into the conversation, so your assistant can act on them.

You build the Flow once, either in Ringg's [Flow builder](/documentation/build-agents/agents/whatsapp-agents/flow-builder) or in Meta's **WhatsApp Manager**, which Ringg picks up automatically. Then any WhatsApp assistant can send it, or a message template can carry it as a button.

<Frame caption="The Flows tab, a Flow's details, adding it to an assistant, a template's Flow button, and the answers in Logs">
  <video alt="The Flows tab, a Flow's details, adding it to an assistant, a template's Flow button, and the answers in Logs" aria-label="The Flows tab, a Flow's details, adding it to an assistant, a template's Flow button, and the answers in Logs" controls muted playsInline className="w-full rounded-xl" style={{ aspectRatio: "16 / 10" }} preload="metadata" controlsList="nodownload noremoteplayback" poster="/media/whatsapp-flows/poster.webp">
    <source src="https://mintcdn.com/ringgai-0da73d20/dn4m-eYKyrW_qwbq/media/whatsapp-flows/video.webm?fit=max&auto=format&n=dn4m-eYKyrW_qwbq&q=85&s=a9c3cc817268a3ce034bf0ea6e48d21e" type="video/webm; codecs=&#x22;av01.0.09M.08&#x22;" data-path="media/whatsapp-flows/video.webm" />
  </video>
</Frame>

## Two kinds of Flow

| | Static Flow | Dynamic Flow (live data) |
| - | - | - |
| What it shows | Only what you typed when building it, plus values your assistant fills in when sending | Screens filled in while the customer is inside the form, such as free time slots from your calendar |
| Good for | Lead forms, feedback, surveys, address or document collection, KYC details | Appointment booking, picking a branch near a pincode, checking stock or prices |
| Setup | This page | This page, then [Flows with live data](/documentation/build-agents/agents/whatsapp-agents/flows-live-data) |

Start with a static Flow. Everything on this page also applies to Flows with live data.

## Before you start

* A connected WhatsApp Business account with at least one **Ready** number. See [Connect WhatsApp Business](/documentation/inventory/tools-integrations/connect-whatsapp).
* A WhatsApp assistant with that number attached. See [Create a WhatsApp agent](/documentation/build-agents/agents/whatsapp-agents/create-an-agent).
* To build in WhatsApp Manager instead of Ringg: access to the same WhatsApp Business account in Meta's [WhatsApp Manager](https://business.facebook.com/wa/manage/home/).

## Build a static Flow

<Tabs>
  <Tab title="In Ringg">
    <Steps>
      <Step title="Open the builder">
        Go to **Tools → WhatsApp Business**, select the **Flows** tab, then **Create Flow**. Name it, for example *Site visit request*, and pick a category.
      </Step>

      <Step title="Design the screens">
        Fill in the first screen's **Short answer**, add questions and text with **Add content**, and add screens with **+**. The preview on the right works like the customer's phone: fill it in to try the Flow.
      </Step>

      <Step title="Save, then publish">
        Select **Save draft**. The draft stays open for editing: select **Cancel** to see its details, then **Publish**, and **Publish** again to confirm. Only published Flows can be sent to customers.
      </Step>
    </Steps>

    Every component, **View as JSON**, **Paste JSON** and changing a published Flow are covered in [Build WhatsApp Flows in Ringg](/documentation/build-agents/agents/whatsapp-agents/flow-builder).
  </Tab>

  <Tab title="In WhatsApp Manager">
    <Steps>
      <Step title="Create the Flow in WhatsApp Manager">
        In WhatsApp Manager, open **Account tools → Flows** and select **Create Flow**.

        * **Name**: something your team will recognise, such as *Site visit request*.
        * **Categories**: pick the closest match, for example *Lead generation* or *Appointment booking*.
        * **Template**: start from one of Meta's templates, or a blank Flow. Choose one **without an endpoint**.
      </Step>

      <Step title="Design the screens">
        Edit each screen in the builder: rename the title, add or remove fields, and change labels. The preview on the right shows exactly what the customer will see.

        Keep it short. Two or three screens with a handful of fields each gets the most submissions.
      </Step>

      <Step title="Save, then publish">
        Select **Save**, check the preview once more, then **Publish**. Only published Flows can be sent to customers.
      </Step>

      <Step title="Find it in Ringg">
        In Ringg, go to **Tools → WhatsApp Business** and select the **Flows** tab. It syncs with Meta every time you open it. Select the refresh icon to sync again at any time.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Field labels matter. Ringg shows the customer's answers under these labels in the chat, in **Logs** and in your webhooks, and your assistant reads them too. *Preferred visit date* is clearer than *Date*.
</Tip>

<Warning>
  Meta locks a Flow once it is published. To change it later, open it in the **Flows** tab and select **Duplicate & edit**, which also works for a Flow made in WhatsApp Manager. See [Change a published Flow](/documentation/build-agents/agents/whatsapp-agents/flow-builder#change-a-published-flow).
</Warning>

### Check what the Flow collects

The **Flows** tab lists every Flow on the account, with its **Status**, how many **Questions** it asks, where its **Live data** comes from, and when it was **Last synced**.

<Frame caption="The Flows tab: two published Flows and two drafts that load live data">
  <img src="https://mintcdn.com/ringgai-0da73d20/dn4m-eYKyrW_qwbq/media/whatsapp-flows/flows-tab.webp?fit=max&auto=format&n=dn4m-eYKyrW_qwbq&q=85&s=ca42c46791c9794b8b9ab44b2b2d481b" alt="Flows table with Site visit request (Published, 5 questions), Book a visit and Find a showroom (Draft, From endpoint) and Visit feedback (Published, 2 questions), each with its Meta Flow ID and last synced time" width="2352" height="592" data-path="media/whatsapp-flows/flows-tab.webp" />
</Frame>

Select a Flow to open its details:

* **The preview** on the right: fill in the form and move between screens as the customer would. The numbers above it jump to a screen. When you submit, it shows the answers and the message your assistant reads.
* **Data source**, for a draft or a Flow that loads live data: where its screens get that data. See [Flows with live data](/documentation/build-agents/agents/whatsapp-agents/flows-live-data).
* **Technical details**: the Flow's Meta ID, its endpoint, and the data each screen takes.

**View on Meta** opens the Flow in WhatsApp Manager.

<Frame caption="A published Flow's details, with its second screen in the preview">
  <img src="https://mintcdn.com/ringgai-0da73d20/-vF1MHd0bJHQ6pVT/media/whatsapp-flows/flow-details.webp?fit=max&auto=format&n=-vF1MHd0bJHQ6pVT&q=85&s=37a767e28c6439cfcb928dc59c2237c6" alt="Site visit request details: Published and Lead generation chips, Technical details, and Duplicate and edit at the bottom; the preview shows screen 2, Visit details, with Project, Preferred visit date and Visitors and a Request visit button" width="1792" height="1640" data-path="media/whatsapp-flows/flow-details.webp" />
</Frame>

## Let your assistant send it

<Steps>
  <Step title="Add the Flow to the assistant">
    Open the WhatsApp assistant in the agent editor. In the left menu, select **WhatsApp Flows**, then **Add flow**, and pick your Flow.

    The list shows published Flows only, so publish a draft from the **Flows** tab first. A Flow that can't be sent is greyed out with the reason, for example *Not read from Meta yet: sync this account's Flows*. If you just published one in WhatsApp Manager, select **Sync from Meta** at the bottom of the list.
  </Step>

  <Step title="Write the message around it">
    The Flow goes out as a chat message with a button. The live preview on the right updates as you type.

    | Field | What it is | Example |
    | - | - | - |
    | **Message** | The text above the button. Required. | *Tap below to pick a slot for your site visit.* |
    | **Button label** | The button that opens the form, up to 20 characters. Required. | *Book a visit* |
    | **Header** and **Footer** | Optional lines above and below the message. | *Green Acres Villas* |
    | **When to send it** | Optional. Plain words telling the assistant when this Flow is useful. | *When the customer wants to visit a project.* |
    | **Opens on** | The screen the form opens on. Usually its first screen. | *Your details* |

    <Frame caption="Setting up Site visit request on an assistant, with the live message preview">
      <img src="https://mintcdn.com/ringgai-0da73d20/dn4m-eYKyrW_qwbq/media/whatsapp-flows/flow-setup.webp?fit=max&auto=format&n=dn4m-eYKyrW_qwbq&q=85&s=dcbddbaa497ca7871f701ae741ad414c" alt="Set up Site visit request dialog: Message, Button label Book a visit, optional Header and Footer, When to send it, and Opens on Your details; the preview shows the message with a Book a visit button" width="2048" height="1640" data-path="media/whatsapp-flows/flow-setup.webp" />
    </Frame>
  </Step>

  <Step title="Prefill what you already know (optional)">
    Under **Prefill**, give a starting value to any field the customer shouldn't have to type again. Leave a field empty and the customer fills it in.

    **Prefill** appears only when the Flow's opening screen takes starting values, which a Flow written in WhatsApp Manager or as Flow JSON declares with `init-value`. Flows from Ringg's builder have none.

    | Type | Where the value comes from | Example |
    | - | - | - |
    | **Static** | The same fixed value every time | `Bangalore` |
    | **Variable** | A custom variable of the conversation | `name` |
    | **Dynamic** | The assistant fills it from the chat. Describe what to put in. | *The city the customer mentioned* |
  </Step>

  <Step title="Save">
    Select **Save**. The Flow appears under **WhatsApp Flows** as a card with its preview. Use the pencil to edit it or the bin to remove it. Its tool name, such as `send_site_visit_request`, is what you tag in the prompt.
  </Step>

  <Step title="Tell the assistant when to send it">
    The assistant only sends a Flow when its prompt says so. In the prompt editor, type `@` and choose the Flow. It is inserted as `@||send_site_visit_request||`. Next to it, say when to send it and what to do with the answers:

    ```text theme={null}
    When the customer wants to visit the site, send @||send_site_visit_request||
    and say "I've sent you a quick form to pick a date."
    When they submit it, thank them, repeat the date they picked, and tell them
    our team will call to confirm.
    ```
  </Step>

  <Step title="Test it">
    Open **Test assistant**, scan the QR code with your phone and ask for a site visit. Open the form, fill it in and submit. The assistant should reply using your answers.
  </Step>
</Steps>

## Where the answers show up

When the customer submits, the answers arrive as their next message, labelled with the Flow's question labels.

<Tabs>
  <Tab title="To your assistant">
    The assistant reads the submission as a message from the customer and replies to it straight away:

    ```text theme={null}
    User submitted the WhatsApp Flow "Site visit request" (sent with send_site_visit_request):
    Full name=Priya Sharma, Preferred visit date=2026-10-02, Visitors=2
    ```

    It can use these answers in its reply, or pass them to an on-call tool, such as your CRM API or a calendar booking tool.
  </Tab>

  <Tab title="In Logs">
    In **Logs → WhatsApp**, open the chat and its **Transcript**. The Flow message appears with its button, and the customer's submission shows as **Response sent**. Select **View response** to see every answer, grouped by screen. See [Chat history](/documentation/monitor/logs#whatsapp-chats).

    <Frame caption="View response in Logs: the answers grouped by screen">
      <img src="https://mintcdn.com/ringgai-0da73d20/dn4m-eYKyrW_qwbq/media/whatsapp-flows/flow-response.webp?fit=max&auto=format&n=dn4m-eYKyrW_qwbq&q=85&s=fa8d88ece9a7df62189b955e5c7cdc14" alt="Your response dialog for Site visit request: Your details with Full name Priya Nair and Phone 9876545012, then Visit details with Project Green Acres Villas and Preferred visit date 2026-10-10, and a Close button" width="896" height="1022" data-path="media/whatsapp-flows/flow-response.webp" />
    </Frame>
  </Tab>

  <Tab title="In your webhooks">
    The chat's `transcript` in [chat events](/documentation/build-agents/customize-agent-behaviour/webhooks/whatsapp-chat-events) includes the submission as a `user` message, in the same text the assistant reads:

    ```json theme={null}
    { "user": "User submitted the WhatsApp Flow \"Site visit request\" (sent with send_site_visit_request): Full name=Priya Sharma, Preferred visit date=2026-10-02, Visitors=2" }
    ```

    To get the answers as separate fields, add them to the agent's **Advanced Analysis**.
  </Tab>
</Tabs>

## Open a Flow from a message template

A Flow sent by the assistant only reaches customers who messaged you in the last 24 hours. To start the conversation yourself, for example a booking reminder after a missed call, put the Flow on a **message template** as a button.

<Steps>
  <Step title="Add a Flow button to a template">
    Go to **Tools → WhatsApp Business**, select the **Message templates** tab, then **New template**. Under **Buttons**, select **+ Flow**.
  </Step>

  <Step title="Pick the Flow">
    * **Button text**: what the button says, up to 25 characters, such as *Book a visit*.
    * **Flow**: one of your published Flows.
    * **Opens on**: the screen it opens on. For a Flow with live data, choose **Loaded by the Flow's endpoint**.

    A template can have up to three buttons, and one of them can be a Flow button.

    <Frame caption="A template's Flow button: its text, the Flow it opens and the screen it opens on">
      <img src="https://mintcdn.com/ringgai-0da73d20/dn4m-eYKyrW_qwbq/media/whatsapp-flows/template-flow-button.webp?fit=max&auto=format&n=dn4m-eYKyrW_qwbq&q=85&s=02c56cb9364ca03935dbaa79fc13b88b" alt="Create message template dialog: the body text, then a Flow button with Button text Book a visit, Flow Site visit request and Opens on Your details; the preview shows the message with a Book a visit button" width="2048" height="1640" data-path="media/whatsapp-flows/template-flow-button.webp" />
    </Frame>
  </Step>

  <Step title="Submit it for review">
    Submit the template. Meta reviews it before it can be sent, as with any template. See [Message templates](/documentation/inventory/tools-integrations/connect-whatsapp#message-templates).
  </Step>

  <Step title="Send it">
    Send the approved template like any other: with the **Send WhatsApp Template** tool [during a call or chat](/documentation/build-agents/customize-agent-behaviour/tools/whatsapp-tools#on-call), or through the [outbound API](/documentation/deploy/whatsapp/start-a-conversation). When the customer submits the form, the answers come back into the chat with the assistant on that number, exactly as above.
  </Step>
</Steps>

## Flow status

Ringg only sends **Published** Flows.

| Status | Meaning | What to do |
| - | - | - |
| **Draft** | Saved but not published. | Publish it from its details in the **Flows** tab. For a Flow made in WhatsApp Manager, publish it there, then sync. |
| **Published** | Live. | Nothing: it can be sent. |
| **Throttled** | Meta is limiting it, usually because of errors or customer complaints. | Check its health in WhatsApp Manager and sync once it is Published again. |
| **Blocked** | Meta stopped it. | Check its health in WhatsApp Manager, or build a new Flow. |
| **Deprecated** | Retired in WhatsApp Manager. | Use another Flow. |

## Troubleshooting

| You see | Where | What to do |
| - | - | - |
| *No Flows on this account yet* | Flows tab | Select **Create Flow**. Or build and publish one in WhatsApp Manager under the same WhatsApp Business account, then select **Sync from Meta**. |
| *No published flows* | The assistant's Flow picker | Publish a Flow from the **Flows** tab, or publish it in WhatsApp Manager and select **Sync from Meta**. |
| *Draft: publish it from the Flows tab* | A template's Flow list, or an assistant's WhatsApp Flows | Open the Flow in the **Flows** tab and select **Publish**. |
| *Draft: publish it in WhatsApp Manager* | A template's Flow list, or an assistant's WhatsApp Flows | Publish the Flow in WhatsApp Manager, then sync. |
| *Not read from Meta yet: sync this account's Flows* | The Flow picker | Select **Sync from Meta**. |
| *Its questions are filled in when it's sent* | The Flow picker | This Flow builds its questions from data at send time, so Ringg can't send it. Use a Flow whose questions are written in the Flow itself. |
| *Uses Ringg's retired form endpoint* | Flows tab and picker | An older form Flow. Open it and use **Set up data source**, or build a new Flow. |
| *Not in this WhatsApp account* | The assistant's Flow list | The Flow was deleted, or the assistant's number moved to another account. Remove it and add another. |
| The assistant never sends the Flow | The chat | Tag the Flow in the prompt with `@` and say when to send it. |
| The customer's form says it can't open | The phone | The Flow isn't published, or it is **Blocked**. Check its status in the Flows tab. |

## Good to know

<AccordionGroup>
  <Accordion title="The 24-hour window applies">
    An assistant sends a Flow as a normal chat message, so WhatsApp only delivers it within 24 hours of the customer's last message. Outside that window, send a template with a Flow button.
  </Accordion>

  <Accordion title="Flows belong to one WhatsApp Business account">
    The Flows tab lists the Flows of the connected account. An assistant can use the Flows of the account its number belongs to.
  </Accordion>

  <Accordion title="Changing a Flow">
    Published Flows can't be edited. Open the Flow in the **Flows** tab and select **Duplicate & edit**, which also works for a Flow made in WhatsApp Manager. Publish the copy, then in the assistant remove the old Flow and add the new one. Update the `@` tag in the prompt too. See [Change a published Flow](/documentation/build-agents/agents/whatsapp-agents/flow-builder#change-a-published-flow).
  </Accordion>
</AccordionGroup>

<RelatedTopics items={[["WhatsApp agents", "/documentation/build-agents/agents/whatsapp-agents/overview"], ["Connect WhatsApp", "/documentation/inventory/tools-integrations/connect-whatsapp"], ["Create a WhatsApp agent", "/documentation/build-agents/agents/whatsapp-agents/create-an-agent"], ["Flow builder", "/documentation/build-agents/agents/whatsapp-agents/flow-builder"], ["Flows with live data", "/documentation/build-agents/agents/whatsapp-agents/flows-live-data"], ["Live data from your server", "/documentation/build-agents/agents/whatsapp-agents/flows-your-server"], ["WhatsApp tools", "/documentation/build-agents/customize-agent-behaviour/tools/whatsapp-tools"], ["WhatsApp chat events", "/documentation/build-agents/customize-agent-behaviour/webhooks/whatsapp-chat-events"], ["Start a conversation", "/documentation/deploy/whatsapp/start-a-conversation"], ["WhatsApp Relay", "/documentation/deploy/whatsapp/relay-overview"], ["WhatsApp Relay integration guide", "/documentation/deploy/whatsapp/relay-integration-guide"], ["WhatsApp Relay troubleshooting", "/documentation/deploy/whatsapp/relay-troubleshooting"], ["WhatsApp chats in Logs", "/documentation/monitor/logs#whatsapp-chats"]]} />


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