Conversation Flows

Conversation Flows let one base assistant route a call through multiple conversation nodes. Each node has its own prompt and optional transitions. During the call, the LLM chooses transitions by calling generated tools such as transition_to_billing or transition_to_support. The model is intentionally small: one JSON document, one base assistant for voice/STT/TTS/tools, Redis-backed live state, and API-first editing.

Flow Shape

{
  "begin_node": "start",
  "global_prompt": "Be concise and helpful.",
  "nodes": {
    "start": {
      "type": "conversation",
      "prompt": "Greet the caller and ask how you can help.",
      "transitions": [
        {
          "kind": "prompt",
          "to": "support",
          "when": "The caller needs product support."
        }
      ]
    },
    "support": {
      "type": "conversation",
      "prompt": "Help the caller with support questions."
    }
  }
}

Runtime Behavior

begin_node is the first node for every call.
global_prompt is applied to every node.
Node prompts are combined with the base assistant prompt.
Transition tools are generated only for the current node’s outgoing transitions.
Dynamic variables such as {{from_number}} are read-only and interpolated into prompts.
Existing assistant tools such as endCall, transfer, DTMF, SMS, and custom tools still come from the base assistant.

What the Base Assistant Controls

The flow graph controls routing and node prompts. The base assistant still controls the rest of the live call stack:

Setting area	Comes from
LLM provider, prompt defaults, fallbacks	Base assistant
TTS voice, cloned voices, background sound	Base assistant
STT provider, turn detection, speculative LLM	Base assistant
Cold/warm transfer, DTMF, SMS, custom tools	Base assistant
RAG documents and retrieval settings	Base assistant
Recording, spam detection, bypass numbers	Base assistant
Nodes, transitions, global prompt, variables	Conversation Flow

The flow editor embeds the same assistant configuration form for the base assistant. If a flow behaves correctly but sounds wrong, uses the wrong tool, or has bad interruption timing, update the base assistant settings.

Node and Transition Design

Use one node for each stable conversational mode: greeting, qualification, billing, support, escalation, booking, or wrap-up. Avoid creating a new node for every question; keep node prompts focused on behavior and use transitions for routing decisions. Transition examples:

{
  "kind": "prompt",
  "to": "billing",
  "when": "The caller asks about invoices, payments, refunds, or account balance."
}

At runtime, Burki exposes only the current node’s transition tools to the LLM. This keeps routing decisions local and reduces accidental jumps across the graph.

Phone Number Assignment

Phone numbers can be assigned to either a single assistant or a ConversationFlow. A flow assignment stores flow_id on the phone number and clears the direct assistant assignment. Use the Flow phone-number endpoints to bind numbers to flows:

curl -X POST https://api.burki.dev/api/v1/flows/42/phone-numbers/7/assign \
  -H "Authorization: Bearer $BURKI_API_KEY"

See the Conversation Flows API reference for CRUD and assignment endpoints.

Common Flow Patterns

Pattern	Use when	Notes
Intake → department routing	The first step is identifying caller intent.	Start node asks one broad question, then routes to department nodes.
Qualification → transfer	AI should qualify before handoff.	Use a warm transfer tool on the base assistant for high-context handoffs.
FAQ → escalation	AI can answer common questions but escalates complex cases.	Keep RAG enabled on the base assistant and transfer scenarios specific.
Appointment booking	Caller needs multi-step scheduling.	Use node prompts for required fields and post-call extraction for structured data.

Getting Started

Core Concepts

AI Providers

Features

Advanced

Help & Resources

Flow Shape

Runtime Behavior

What the Base Assistant Controls

Node and Transition Design

Phone Number Assignment

Common Flow Patterns

​Flow Shape

​Runtime Behavior

​What the Base Assistant Controls

​Node and Transition Design

​Phone Number Assignment

​Common Flow Patterns

Flow Shape

Runtime Behavior

What the Base Assistant Controls

Node and Transition Design

Phone Number Assignment

Common Flow Patterns