Authoring Flows

A flow is a named sequence of steps that guides a user through a workflow in your product. Flows are JSON objects stored in the KiBee API and executed client-side by the SDK.

Flow structure

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier used in `runFlow()` and API calls.
`title`	`string`	Yes	Human-readable name shown in the Admin Console.
`pageId`	`string`	Yes	The page this flow belongs to. Must match your `identifyPage()` calls.
`goal`	`string`	Yes	What this flow accomplishes. Used by intent matching to rank flows.
`introMessage`	`string`	No	Message the bee speaks when the flow starts.
`phrases`	`string[]`	No	Trigger phrases for intent matching, e.g. `["invite team", "add a user"]`.
`audience`	`string`	No	Who this flow is for. Displayed in the Admin Console.
`steps`	`FlowStep[]`	Yes	Ordered list of commands. See Flow Commands.

Complete example

JSON

{
  "id": "invite-team",
  "title": "Invite your team",
  "pageId": "settings",
  "goal": "Guide a workspace admin through inviting a teammate",
  "audience": "Admins setting up their workspace",
  "introMessage": "Let's invite a teammate. I'll walk you through it.",
  "phrases": ["invite someone", "add a user", "invite team", "add team member"],
  "steps": [
    {
      "type": "fly_to",
      "target": { "kibeeId": "invite-email" },
      "message": "Enter your teammate's email address here."
    },
    {
      "type": "wait_for_input",
      "target": { "kibeeId": "invite-email" },
      "timeoutMs": 30000
    },
    {
      "type": "fly_to",
      "target": { "kibeeId": "invite-role" },
      "message": "Choose their role in the workspace."
    },
    {
      "type": "wait_for_click",
      "target": { "kibeeId": "invite-role" },
      "timeoutMs": 30000
    },
    {
      "type": "fly_to",
      "target": { "kibeeId": "send-invite" },
      "message": "Send the invite — they'll get an email with a join link."
    },
    {
      "type": "wait_for_click",
      "target": { "kibeeId": "send-invite" },
      "timeoutMs": 30000
    },
    { "type": "celebrate", "message": "Invite sent!" },
    { "type": "end_flow", "status": "completed" }
  ]
}

Creating flows

Via the Admin Console

Go to Admin → Flows, click New flow, and fill in the form. The console validates your target IDs against registered targets and previews the step sequence.

Via the API

POST /admin/flows

curl -X POST https://api.kibee.ai/admin/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "invite-team", "title": "Invite your team", ... }'

Design principles

One goal per flow. Separate “invite team” from “change billing” even if both happen on the same page.
Match the user's mental model. Write step messages from the user's perspective, not internal product terminology.
Keep steps atomic. Each step should ask for exactly one action. Multiple instructions in one step cause users to miss things.
Always end with end_flow. Without it the session stays active and friction tracking is incomplete.

See Flow Commands for the full list of step types, or Intent Matching to learn how KiBee maps user questions to flows automatically.