Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.burki.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 areaComes from
LLM provider, prompt defaults, fallbacksBase assistant
TTS voice, cloned voices, background soundBase assistant
STT provider, turn detection, speculative LLMBase assistant
Cold/warm transfer, DTMF, SMS, custom toolsBase assistant
RAG documents and retrieval settingsBase assistant
Recording, spam detection, bypass numbersBase assistant
Nodes, transitions, global prompt, variablesConversation 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

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