/dashboard/bots/create is a stepped form. The page (src/pages/BotCreate.tsx) owns no field state itself — it delegates all of it to the useBotForm hook and renders one step component at a time inside StepWizard.
The Six Steps
TheSTEPS array in BotCreate.tsx defines the order:
| # | Step | Component | Covers |
|---|---|---|---|
| 0 | Identity | StepIdentity.tsx | Name, opening message, re-engagement |
| 1 | Instructions | StepInstructions.tsx | Static/dynamic prompts, post-call analysis, QC, auto dispositions |
| 2 | Policy | StepPolicy.tsx | Conversation Policy engine config |
| 3 | Voice Pipeline | StepVoicePipeline.tsx | STT / LLM / TTS provider cards |
| 4 | Behavior | StepBehavior.tsx | VAD, interruption, runtime timing |
| 5 | Tools & Integrations | StepToolsIntegrations.tsx | Tools, transfer, SIP headers, CRM fetch, post-call push, knowledge base |
There is no standalone “Knowledge” step. Knowledge-base attachment (
StepKnowledge.tsx) is rendered at the bottom of the Tools & Integrations step, not as its own wizard step.StepWizard Shell
components/bot/StepWizard.tsx is a presentational shell: a clickable stepper bar, an animated content area (Framer Motion), and Previous / Continue / Submit / Cancel navigation. It takes steps, activeStep, onStepChange, onSubmit, submitLabel, submitting, and onCancel. The last step shows the submit button instead of Continue. Stepper segments are clickable, so users can jump between steps freely.
useBotForm
src/hooks/useBotForm.ts is the single source of truth for the form.
| Returned member | Purpose |
|---|---|
form | The full BotFormState (flat field bag) |
set(key, value) | Update one field |
setProvider(type, provider) | Switch STT/LLM/TTS provider and reset its model |
errors | Current validation errors keyed by field |
validate() | Returns an errors object; empty means valid |
serialize() | Builds the nested API payload for POST/PUT |
deserialize(bot) | Loads an existing bot into the flat form (used by edit mode) |
| Re-engagement helpers | addReEngagementMsg, updateReEngagementMsg, removeReEngagementMsg |
| Transfer helpers | addTransferTarget, updateTransferTarget, removeTransferTarget |
STT_MODELS, LLM_MODELS, TTS_MODELS) and the transfer-target types live in this hook too.
Submit & Validation Routing
handleSubmit calls validate(). On errors it maps the first failing field to its owning step via errorToStep() and jumps the wizard there, then toasts the first message. On success it serialize()s and POST /api/v1/bots, then navigates to the new bot’s detail page.
errorToStep mapping:
| Error keys | Step |
|---|---|
name, opening_message | 0 (Identity) |
system_prompt, static_system_prompt, dynamic_runtime_prompt | 1 (Instructions) |
conversation_policy_* | 2 (Policy) |
custom_tools, transfer_targets, crm_prefetch_url, post_call_push_url, sip_allowed_headers, sip_transfer_passthrough_headers | 5 (Tools) |
Step Highlights
Identity
Bot name, opening message, and an optional re-engagement block (aDynamicList of messages plus first-gap, subsequent-gap, and max-retries numbers using the blur-default pattern).
Instructions
When Conversation Policy is enabled, only a Fallback System Prompt is shown (the live prompt comes from the policy engine). Otherwise it splits into a cacheable Static System Prompt (no{{}} variables) and a Dynamic Runtime Prompt (per-call {{crm.*}}/{{call.*}}/{{system.*}}). Editing the static field also mirrors into system_prompt. Collapsible sections cover Post-Call Analysis (with a callback-detection toggle), Quality Control, and Auto Dispositions.
Voice Pipeline
ThreeProviderCards (STT/LLM/TTS). Switching a provider via setProvider resets the model list for that stage. STT exposes turn-detecting-STT-specific fields (eot thresholds, language hints, vad_force_turn_endpoint) and TTS exposes voice, prosody, pronunciation dict, and cache settings.
Tools & Integrations
End Call, Transfer Call (with transfer targets and pre-transfer message), SIP header whitelist, Agent Desk handoff context (ADK only), Voicemail Detection, the Custom Tools builder, Pre-Call Fetch, Post-Call Push, and the Knowledge Base section.Related Docs
Tool Builder
The visual mid-call tool builder used in step 5.
Bot Detail & Integration
Edit mode reuses the same steps and hook.
Design System
FormField, Section, Toggle, and number-input patterns.
Create a bot (ops)
Operator-facing build guide.