Bot Flow Builder
The Bot Flow Builder lets you draw a guided conversation for your chat widget: the questions the bot asks, the buttons visitors can tap, where each answer leads, and where the collected answers go. Use it when you want a fixed, predictable path — lead intake, application forms, qualification questions, or a greeting menu — instead of a fully free-form AI chat.
The Bot Flow Builder is enabled by the Knock Knock team — contact support to turn it on for your account. Until then, Settings > AI Agents > Bot Flow is hidden.
Each account has one bot flow. Once published, it runs in your chat widget for every visitor.
Getting Started
Go to Settings > AI Agents > Bot Flow. The first time you open it, pick a starting point:
| Template | What you get |
|---|---|
| Blank | Start and End, ready for your own steps. |
| Copilot bot (Recommended) | A greeting menu: your AI answers questions from your knowledge base, and Start my application asks 10 questions and sends the answers to your site. |
| Lead intake (10 questions) | Business name, volume and contact details, then sends the answers to your site. |
You can also Import JSON — either a flow you exported earlier or a simple list of questions. An import loads as a draft; press Save to keep it.
The Builder
The page has two tabs: Builder (the canvas) and Submissions (every set of answers visitors have sent).
On the canvas, drag steps from the palette, connect them, and click a step to edit it in the side panel. The toolbar has Undo, Redo, Auto-layout, Import, Export and Test. Keyboard shortcuts: Ctrl+Z undo, Ctrl+Shift+Z redo, Del removes the selected step or connection.
Step Types
| Step | What it does |
|---|---|
| Start | Where the conversation begins. Can carry an optional greeting. |
| Message | The bot says something. Supports **bold**. |
| Link button | Shows a button that opens a URL in a new tab. |
| Ask: text | Free-text answer, saved to a variable. |
| Ask: buttons | Visitor taps an option; each button is its own output, so every option can branch. |
| Condition | Branches on an answer — a yes and a no output. |
| Send data | Delivers the answers to your website or a webhook. |
| AI answer | Hands the chat to your AI agent. |
| Talk to human | Ends the flow and connects the visitor to an available team member. |
| End | Optional closing message; the flow stops. Visitors can still chat normally afterwards. |
Questions
Both question steps save the answer to a variable (Save answer to variable). Options:
- Answer must be — Any text, Email, Phone number, Number or Address. Invalid answers are re-asked with a short hint.
- Answer required
- Skip if already answered — if the variable already has a value, the question is skipped.
- Number this question — counts it in the "3/10 ·" progress prefix. Turn it off for menu-style questions.
- Visitors can also type an answer (buttons only) — typed text that matches no button follows the Typed answer output.
A buttons step can leave the question empty to show only the buttons.
Conditions
A Condition step compares a variable using: equals, does not equal, contains, is greater than, is less than, is empty, is not empty.
AI Answer
By default an AI answer step ends the flow and the chat continues with your Chat Agent and its knowledge base. Turn on Come back to the flow after answering to use it mid-flow instead: the AI answers the visitor's last answer (for example, the button they tapped), then the flow carries on from this step. With that on you can also:
- Write Your answer — the bot replies with your fixed text instead of asking the AI.
- Turn on AI suggests follow-up buttons — the AI adds 2–3 buttons that fit its answer, shown before the next buttons step's own buttons.
Flow Settings
When no step is selected, the side panel shows Flow settings (on narrow screens, open it with the Flow settings button):
- When does the flow start? — When chat opens (the bot starts right away) or On a button (the visitor taps a start button; set its Start button label, default "Get started").
- Show progress — prefixes numbered questions with "3/10 · ".
- Let AI answer side questions — if a visitor types a question instead of an answer, your AI agent replies once, then the question repeats.
The panel also lists the variables the flow collects and counts its steps, questions and connections.
Sending the Answers
A Send data step delivers everything collected so far. Under Send the answers to, pick one or both:
- Your website — prefills a form on the page that embeds the widget. Enter the Allowed site origin (for example
https://www.yoursite.com— scheme and host, no path); the widget only posts the answers when it is embedded on exactly that origin. Copy the Listener for your site snippet onto that page. - Webhook — POSTs JSON to your server. HTTPS only, and it is sent from our servers, never from the visitor's browser. Failed deliveries are retried up to 3 times.
Every submission is also saved and listed under Submissions, whichever destinations you pick.
Shape the payload in the same panel: map each variable to a Payload key under Fields, add Static fields, and tick System fields (conversation ID, submission time, page URL, flow name). Nested keys turns dotted keys like biz.dba into nested objects. Event type and Wrapper key control the outer envelope. The Live payload preview shows exactly what the widget and webhook will send, with sample values.
Webhook Security
- Signing secret — click Generate (or Rotate). The secret is shown once; requests then carry an
X-KK-Signatureheader:sha256=followed by an HMAC-SHA256 of<timestamp>.<raw body>. - Bearer token (optional) — sent as
Authorization: Bearer …. - Send test — sends one signed sample request to your webhook URL.
Testing and Publishing
Click Test to run the flow in a preview chat, with the collected data shown alongside. AI steps are simulated in the test; nothing is sent to your webhook.
Your edits are a Draft until you click Publish (or Publish changes once a version is live). Publishing checks the whole flow first and jumps to the first broken step if something is wrong — every output must be connected, every step must be reachable from Start, and each question must save to its own variable. Unpublish stops the widget running the flow.
In the Chat Widget
When a flow is published, the chat widget runs it: questions show the "N/total" progress, answers are validated, and buttons branch as you designed. The whole exchange — bot prompts and visitor answers — is saved to the chat transcript, so it appears in Chats like any other conversation. Running the scripted steps does not use AI credits; only AI answer steps do.
Submissions
The Submissions tab lists each submission with its date, status (completed or partial), answers and delivery result — "Saved only" when no webhook was configured, otherwise whether the webhook accepted it.
Limits
- One bot flow per account, up to 300 steps and 600 connections.
- Messages and answers are capped at 2,000 characters.
Next Steps
- Chat Agent — the AI your flow hands off to.
- Knowledge Base — what the AI answers from.