Call routing flows

Every imported number is wired to a routing flow — a visual flowchart of decisions and actions that runs synchronously when the call arrives. The routing executor walks the flow node by node, emits TwiML at each step, and falls back to a safe default if a node exceeds its latency budget.

Open Settings → AI Phone → Call Routing to manage flows.

The 9 routing node types

Node	What it does
CALLER_LOOKUP	Looks up the caller's number in your client database and attaches the match (client name and record) to the call for later nodes to use.
BUSINESS_HOURS_GATE	Checks if the call arrived inside your Location's business hours. Branches open/closed.
SHIFT_GATE	Checks if a specific staff member or role is on shift right now (uses RosterShift + ActiveShift).
RINGDOWN_SEQUENCE	Tries N receptionists in order with a per-target timeout. Advances on busy/no-answer.
CALL_QUEUE	Places the caller in a named queue with hold music and a timeout escape.
FORWARD_EXTERNAL	Dials a single external E.164 (e.g. your mobile). For after-hours overflow.
AI_RECEPTIONIST_FALLBACK	Forwards to your reception number in opening hours; otherwise takes a voicemail. No AI answers the call.
RECORD_CONSENT_GATE	Legacy step kept so older flows still run. It passes the call straight through.
VOICEMAIL_DROP	Records voicemail with your greeting and a maximum length.

Every flow must end in a terminal node. The default terminal is AI_RECEPTIONIST_FALLBACK — if all other paths fail, the call forwards to your reception number in opening hours or goes to voicemail, so the caller is never dropped. See Call handling and voicemail.

Starter templates (coming soon)

Five templates are being seeded for common practice shapes:

Template	Suits
Solo practitioner	Single-receptionist or solo psychologist.
Small clinic	2–5 receptionists; ring-down + voicemail fallback.
Group practice	6+ practitioners; queue with hold music.
1300 reception	High-volume inbound on a 1300 with shift gates.
After-hours	Business-hours gate + voicemail outside hours.

Until the templates land, "Create routing flow" opens the visual workflow builder (under Workflows) with the PHONE_ROUTING category preselected.

Latency budget

Each node must complete quickly (the executor warns at 500 ms and hard-stops a node at 1 second). On timeout, the call takes the safe-fallback path: dialling your fallback number if one is configured, or a brief apology message.

• Per-execution 8-second total elapsed circuit breaker — Twilio's webhook hard timeout is ~15 s, so this leaves headroom.

The safe-fallback TwiML ensures the caller is never dropped: if every gate trips, the call still rings to your configured fallback E.164.

Editing flows

Routing flows are stored as WorkflowDefinition rows with category = 'PHONE_ROUTING'. The workflow builder at /workflows/[id]/edit provides the drag-and-drop canvas — drag nodes from the palette, draw edges between them, fill in per-node configuration.

Once saved, the flow takes effect on the next incoming call. There's no deploy step — changes propagate immediately.

Assigning a flow to a number

Open Settings → AI Phone → Numbers, click on a number, and pick the flow from the dropdown. A number can only have one active flow at a time, but you can switch flows freely (e.g. swap to a holiday flow before Christmas, then switch back).