# Flows (Visual Builder)

## Overview

Flows are visual automations that guide a WhatsApp conversation step by step: send a message, ask a question, branch on the answer, wait, call an AI model, book an appointment, add a row to Google Sheets, sell a product, and more. Find them under Flows in the navigation, where you build them on a drag-and-drop canvas.

A flow is made of steps (called nodes) joined by connectors that show the path from one step to the next. Exactly one step is the trigger — the entry point that decides which contacts enter the flow and when. You design the flow on the canvas; when you save, it's stored securely, and when it runs, WaDesk walks through the steps one by one and sends the right WhatsApp message for however your number is connected.

> Works with any setup. The builder works on all three WhatsApp connections. The same step sends correctly whether your number runs on the Unofficial API, the official Cloud API, or Twilio. Where a connection can't show something the normal way (Twilio has no tappable buttons or lists, for example), WaDesk falls back to a numbered text menu and reads the number the customer types back. See Engine notes.

## Core Concepts

- Draft → Live → Paused: a new flow starts as a draft. Publishing makes it live. Turning a live flow off makes it paused — it stops running but keeps its design. The list shows each flow as live, paused, or draft.
- Trigger step: exactly one per flow, always the first step. Every save records the trigger so WaDesk can quickly find which flows a tag or group should start, without opening the whole flow.
- Variables & merge tags: question steps save the customer's answer into a named variable. Reuse it later in any message with a `{{var}}` tag (for example `Thanks {{name}}!`). WaDesk fills in the saved value when the message is sent.
- Branches: some steps split the path. A Condition has yes / no; Book Appointment has booked / no slots; commerce steps have purchased / abandoned; multiple-option steps (Buttons, List, Poll) give you one branch per option. Wire each branch to a different next step.
- Subscribers: every contact running through a flow is a subscriber, shown as active, paused, completed, or failed. You can view and pause/resume them per flow.
- Scoped to workspace and connection: flows belong to a workspace, and the list shows the flows for your workspace's current WhatsApp connection. Any teammate with the admin role can build and manage them.

## Triggers

The trigger's type decides how contacts enter the flow. There are four types:

Trigger type | Fires when
--- | ---
Keyword | A customer sends a WhatsApp message matching one of your keywords (e.g. `hi, hello, start`).
Tag added | A specific tag is added to a contact (manually, by a rule, or by a Tag step in another flow).
Group join | A contact is added to a specific contact group.
Manual enroll | You add contacts in by hand from the flow's Enroll action (by selecting contacts or a group).

### Setting the trigger

1. Open the flow and click the trigger step (always first on the canvas).
2. In the side panel pick the type: Keyword, Tag added, Group join, or Manual enroll.
3. For Keyword, type a comma-separated list of keywords.
4. For Tag added / Group join, choose the tag or group from the dropdown (your real tags and groups are listed, so you just pick one).
5. Optionally bind a device (see Device binding) to decide which connected number launches the flow.
6. Save the flow. If you later rename a tag or change the trigger type, just save again to keep everything in sync.

> How matching works. When a tag is added or a contact joins a group, WaDesk finds the published and active flows whose trigger matches and adds the contact to each. Keyword triggers are matched against incoming messages. A draft or paused flow never enrolls anyone.

## Step Reference

The palette groups steps by purpose. The tables below list every step you can use. "Branches" shows where you can wire the path onward from that step.

### Messaging steps

Step | What it does | Branches
--- | --- | ---
Message | Send a single text message (can include `{{var}}` personalisation). | One path onward
Sequence | Send several replies in order — text, image, video, audio, or document — as one step, with a short pause between each. | One path onward
Media | Send one image, video, audio, or document, with an optional caption. | One path onward
Template | Send an approved WhatsApp template by name. WaDesk loads its content when you save, so it sends fast. | One path onward
CTA | Action buttons — up to 3, combining Visit (link), Call (phone), and Copy (code). On the official Cloud API only one link shows as a tappable button; the rest appear in the text. | One path onward
Location | Send a location pin (name, address, coordinates). | One path onward
Poll | Send a poll with 2–12 options; optionally allow multiple choices. | One per option

### Input & branching steps

Step | What it does | Branches
--- | --- | ---
Ask | Ask a question and save the typed answer to a variable. You can require the answer to be a valid email, phone, or number. If you list expected answers, the reply is routed down the matching branch. | One per expected answer, or one path onward
Buttons | Reply buttons (max 3). Each option gives you a branch so you can react to the tap. | One per option
List | An interactive list (up to 10 rows). Each option gives you a branch. You can set the "open list" button label. | One per option
Condition | Split the path based on one or more variable rules combined with AND/OR. | yes / no
Delay | Wait a set amount of time (seconds, minutes, hours, or days) before continuing. | One path onward

Condition checks: equals, does not equal, contains, does not contain, greater than, less than, and is empty. Text comparisons ignore capitalisation and surrounding spaces; greater than / less than treat both sides as numbers. With several rules, you choose AND/OR between them; the flow takes the first match.

### AI, actions & integrations

Step | What it does | Branches
--- | --- | ---
AI assistant | Ask an AI model a question (with the conversation as context), then save and send the reply. You can only pick the providers your admin enabled. | One path onward
Chatbot | Hand the conversation to one of your AI agents for a self-contained chat. | One path onward
Tag | Add or remove a tag on the contact. Use an existing tag or type a new name to create one. | One path onward
Assign agent | Hand the conversation to a team queue (or a specific agent) with an internal note. | One path onward
Webhook | Call another system over the internet (your variables can be inserted into the request) and optionally save the response to a variable. | One path onward
Sub-flow | Run another flow, then come back and continue this one. | One path onward
Book appointment | Offer open slots as a list, book the chosen one on your calendar, and confirm. | booked / no slots
Google Meet | Create a Google Meet link and send it during the flow, with a lead time before the meeting starts. | One path onward
Google Sheets | Add a row to a spreadsheet, or look up a row by a matching value and save its cells into variables. | One path onward
Google Docs | Copy a template document, fill in the placeholders, share it with anyone who has the link, and send the link. | One path onward
Google Form | Send a Google Form link and pause; the flow continues once the form is submitted. | Continues on submit
WhatsApp Form | Send a published WhatsApp Form as an interactive message. Official Cloud API only. | One path onward
WhatsApp Shop / WooCommerce / Shopify | Send a product list or catalog and watch for a purchase. The purchased branch runs when the customer buys; abandoned runs after the wait time if they don't. | purchased / abandoned
End | Stop this branch of the flow. | —

If a step ever can't be understood (for example, after a future change), it's skipped with a warning rather than breaking the whole flow.

> Connection notes (quick view): the WhatsApp Form step only works on the official Cloud API connection. The Google steps need the workspace's Google account connected (the same connection used for Calendar). On Twilio, the tappable steps (Buttons, List, CTA) become numbered text. Full detail in Engine notes.

## Build & Connect a Flow

1. Go to Flows and click Create Flow (or open an existing one to edit).
2. Give the flow a name and optional category.
3. Set up the trigger step first — pick the type and, where relevant, the tag, group, or keywords (see Setting the trigger).
4. Drag steps from the palette onto the canvas. The layout reads left to right.
5. Connect steps: drag from a step's output to the next step. Branching steps have several branches — wire each to a different next step. For a Condition, wire yes and no; for Buttons/List, wire one per option; for commerce, wire purchased and abandoned.
6. Open each step and fill in its settings. Use `{{var}}` tags in any message to reuse answers captured by earlier Ask steps.
7. End every branch with an End step (or a final message). An unconnected branch simply ends the flow there.
8. Click Save. The flow is stored, ready to run.
9. Click Publish to make it live. Use Pause later to stop enrolling new contacts without deleting it.

> Variables tip. An Ask step saves into the variable you name (default `answer`); Buttons/List save into `choice` by default; the AI assistant saves into `reply`; a Webhook saves the response into `response`. Pick clear names and reuse them as `{{name}}`, `{{choice}}`, etc.

## Build with AI

The builder can generate a starter flow from a plain-language description. Describe the automation (for example, "Greet the customer, ask their name, then offer a list of services and book an appointment") and WaDesk drafts a full flow — steps and connections — onto the canvas for you to refine.

1. Open the builder and start AI generate.
2. Pick a provider and model — you can only pick the ones your admin enabled.
3. Type your description (up to 2000 characters) and generate.
4. Review and edit the result, then save and publish as usual.

How it works: the AI is instructed to build a clean flow — one trigger first, every branch finished, a left-to-right layout, `{{var}}` tags, and no emojis — and the result is capped to a sensible size (up to 20 steps) before it appears on the canvas. You'll get a clear error if the provider isn't enabled or the AI returns something unusable.

> Always review generated flows. The AI produces a starting point. Check the trigger, the wording, every branch, and any device/tag/group choices before publishing — and test against your own number first.

## Device Binding

A flow sends from one of the workspace's connected numbers. You can pick a specific number on the trigger step, or leave it unset to use the workspace default.

- The number picker matches your connection: on the Unofficial API it lists your paired, active phones; on the official Cloud API or Twilio it lists your connected numbers.
- If you pick a number, the flow uses it — as long as it's still active and in this workspace.
- If you don't pick one (or the chosen one is gone), the flow uses the workspace's first active number.
- If no number is available when the flow tries to launch, the subscriber is marked failed with "No connected device for this workspace" — connect a number and enroll the contact again.

## Google, Commerce & Media Pickers

- Google pickers. The Google Sheets / Docs / Form steps let you pick a real spreadsheet, template document, or form from your connected Google account, and match its placeholders or columns to flow variables. These steps need the workspace's Google account connected — the same connection used for Calendar and appointments.
- Commerce pickers. The WhatsApp Shop / WooCommerce / Shopify steps let you pick a store and then choose products from it. Product details (name, image, price) are saved with the step so the cards display instantly. Older flows keep working — their products are upgraded automatically.
- Media upload. The Media and Sequence steps accept image, video, audio, and document files. Uploads are capped at 50 MB.

## Enrolling & Subscribers

- Keyword / tag / group flows enroll contacts automatically when the matching event happens — but only while the flow is published and active.
- Manual-enroll flows are added by you: open the flow, choose contacts or a group, and enroll. The flow must be active. Enrolling the same contact twice does nothing if they're already running; a contact who previously failed gets retried.
- Subscriber states: active, paused, completed, failed. The flow's detail panel lists subscribers with their state, when they were enrolled, and any failure reason; the flows list shows active/completed/failed counts per flow.
- Pause / resume a subscriber: pausing keeps that contact from being re-enrolled by tag/group triggers while you keep them muted. It doesn't stop a conversation already in progress. Resuming clears the pause and any failure, but deliberately doesn't restart the flow (that would double up on contacts mid-conversation).

> Ban safety. Flows send real WhatsApp messages. On the Unofficial API engine, aggressive automated sends to many cold numbers are a fast path to a number ban. Keep delays sensible, only enroll contacts who opted in, and avoid blasting identical messages to large audiences. Test new flows against your own number before going live.

> Do not test with live sends to real contacts. A published flow on a connected workspace will actually message people. When testing, use a throwaway test contact you control — never enroll a real audience just to "see if it works".

## How a flow runs

When a contact is enrolled, WaDesk starts a live conversation for that customer and works through the steps:

- Step by step. The flow begins at the first step and follows the connections. After each step it takes the branch the customer's reply chose and runs the next step. When a branch has nothing connected, that path ends.
- Reading replies. For Buttons, List, Poll, and Ask-with-options, the customer's reply chooses a branch. WhatsApp can send a reply in several different forms, and WaDesk understands all of them, so a tap is routed correctly on any device or carrier. Typing a plain number ("1", "2"…) also works as a fallback.
- 1-hour wait window. A step that waits for the customer (List, Buttons, Ask, Poll, commerce) keeps the conversation open for up to 1 hour. Idle conversations are cleaned up after that — long enough for a person to read and tap, short enough not to pile up.
- Delays. A Delay step simply waits the time you set before moving on.
- Commerce waits. A commerce step pauses for the wait time you set. If the customer buys, the flow takes the purchased branch; if the time runs out first, it takes abandoned. The conversation isn't cancelled while waiting — a late reply can still produce a checkout link.
- Appointments. Book Appointment fetches open slots, sends them as a list, books the chosen one on your calendar, sends a confirmation, and takes the booked branch (or no slots if nothing is free or the reply can't be matched).

## Engine Notes

Each step is sent through your workspace's current WhatsApp connection. Behaviour differs as follows:

Capability | Unofficial API | Official Cloud API | Twilio
--- | --- | --- | ---
Text / media / location | Full support | Full support | Full support
Buttons | Tappable buttons | Tappable (max 3, labels trimmed to 20 characters) | Falls back to numbered text; customer types the number
List | Tappable list | Tappable (up to 10 sections of 10 rows) | Falls back to numbered text
CTA link | Tappable | One tappable link button | Link shown in the message text
Template | Sent as plain text | Sent as an approved template | Approved Twilio template if set up, otherwise plain text
WhatsApp Form | Not available | Supported | Not available
Commerce (catalog / products) | Product cards + checkout link | Native product list / single product | Product cards + checkout link

- Tappable steps fall back on Twilio. Twilio handles interactive content differently, so WaDesk shows a numbered text menu and reads the number the customer types. Flows stay fully usable on Twilio.
- WhatsApp Form is Cloud API only. The step does nothing on the Unofficial API or Twilio; it needs a published WhatsApp Form.
- Google steps need the Google connection. Connect Google (the same one used for Calendar and appointments) before using Sheets, Docs, Form, or Meet.
- Branding footer. If your plan adds a branding footer, it's automatically added to outgoing text and interactive messages (templates excepted).

## Manage Flows

- Duplicate: copies a flow as a fresh draft (titled " (Copy)") so you can iterate without touching the live version.
- Pause / resume: a paused flow stops enrolling new contacts but keeps its design.
- Publish / Unpublish: publishing makes the flow live; unpublishing returns it to draft.
- Delete: removes the flow. Flows belong to your workspace; teammates in the same workspace can manage them.
- Filter: the list filters by status (live / paused / draft), category, and name, and highlights your most-used flows.
- Plan limits: your plan sets how many flows you can create. Editing existing flows doesn't count against the limit.

## Troubleshooting

Symptom | Likely cause & fix
--- | ---
Contacts aren't being enrolled by a tag/group trigger | The flow must be both published and active, and the trigger's tag/group must match. Save the flow again after editing the trigger.
Subscriber shows failed — "No connected device" | No active number in the workspace when the flow tried to launch. Connect a number (or pick one on the trigger) and enroll again.
Subscriber failed — "Contact has no usable mobile number" | The contact has no valid phone. Fix the contact, then enroll again.
Subscriber failed — a connection / server error | The flow engine couldn't be reached. Confirm it's set up and running in admin settings.
Buttons / list show as a numbered text menu | Expected on Twilio. The customer types the number and it routes to the right branch.
The "abandoned" branch never fires | Connect the abandoned branch on the commerce step — an unconnected branch just ends the flow. Also confirm a wait time is set.
WhatsApp Form step does nothing | It is Cloud API only and needs a published WhatsApp Form. Publish the form first.
AI generate / AI step fails | The provider must be enabled by your admin. Pick an enabled provider/model, or contact your admin. If it reports "no workspace", refresh the page.
Flow times out mid-conversation | Steps that wait for a reply give the customer 1 hour. If they don't respond in time the conversation ends — they'll need to start the flow again.
Can't create another flow | You've hit your plan's flow limit. Delete an unused flow or upgrade.