Bot Flows
Build visual WhatsApp automations with drag-and-drop nodes, keyword triggers, and AI-powered responses.
Overview
Bot flows replace simple keyword bots with a visual builder. Each flow is a graph of connected nodes. When a customer messages you, the engine matches a trigger, walks through nodes, and sends WhatsApp replies automatically.
Access: Bot Flows in the sidebar → Create Flow → open the Builder.
Create a flow
menu). Open them in the builder to learn, then edit or delete anytime.
-
Create flow
Go to Bot Flows → Create. Give it a name and slug.
-
Open builder
Click the flow name to open the visual builder at
/bot-flows/{id}/builder. -
Configure trigger
In the Start node panel, set trigger type (default, keyword, or Meta ad).
-
Add nodes
Drag nodes from the palette, connect them, and configure each node's content.
-
Save
Click Save Graph. Test by sending the trigger keyword from WhatsApp.
Flow triggers
| Trigger | When it runs | Example |
|---|---|---|
| Default | Once per new customer (first message only) | Welcome message when a customer messages for the first time |
| Keyword | Customer sends matching text | Keyword "demo" (exact) or "price" (contains) |
| Meta Ad | Customer clicks a Click-to-WhatsApp ad | Ad ID or ad name from referral data |
Only one flow can be marked as default. Keyword flows take priority when they match.
The default welcome flow runs once per customer on their first message only. It does not repeat when later messages do not match any keyword or ad.
Node types
| Node | Purpose |
|---|---|
| Start | Entry point and trigger configuration |
| Text Message | Send plain text reply |
| Media | Send image, video, document, or audio |
| Reply Buttons | Up to 3 quick-reply buttons |
| CTA Button | Website link or call button |
| List Menu | Scrollable menu with up to 10 options |
| Template | Send an approved WhatsApp template |
| Keyword Branch | Route to different paths by keyword |
| AI Agent | Generate smart replies using your AI provider |
| Agent Handoff | Transfer conversation to a human agent |
| End | Stop the flow |
Flow builder tips
- Every flow must have exactly one Start node connected to the graph
- Button and list nodes create multiple output branches — connect each branch
- Condition nodes route by keyword match on the customer's reply
- Upload media in the builder for media nodes (stored per flow)
- Bot replies are sent immediately — no queue delay for flow responses
- Flow state is saved per conversation — customers can continue multi-step flows
Reply buttons & list menus
These behaviors are automatic on every Reply Buttons and List Menu node:
- Invalid text — If the customer types free text instead of tapping a menu option, the bot sends a sorry message and re-sends the same menu.
- Persistent menu (re-selection) — Menus keep working after a branch finishes. If the customer already chose an option (e.g. Pricing) and later picks a different option from that same menu (e.g. Contact Us), the bot goes straight to the new option's reply — no need to restart the flow.
- Works for lists too — WhatsApp disables re-tapping a list message once a row is chosen, so the customer can pick a different past item by simply typing the option name — the bot matches it to that menu and continues from there.
Behavior is controlled by switch_mode in core/config/bot-flow.php:
'direct' (default) jumps straight to the new option, while 'confirm' asks Yes / No first.
You can also customize invalid_menu_input, switch_confirm, and switch_declined.
Agent handoff
The Agent Handoff node changes the conversation status from bot to agent. The conversation appears in the live chat inbox for your team.
- Optionally assign to a specific agent in the handoff node
- Account owners can manually assign chats from the chat header
- AI nodes can also route to handoff on error or when customer asks for a human
- If the customer later sends a keyword trigger (e.g.
menu), the matching bot flow starts again and the chat returns to bot mode