Settings — Call Preferences
Audience: Sales · Support · QA · Management · Engineering · Where in app: Settings → Call Preferences (/settings/calls/preferences) · Plan availability: All plans — gated by settings.calls; AI options require AI calling enabled
The Call Preferences screen (titled "Call Settings" in the UI) controls how an incoming visitor call is handled: whether the AI greets first, whether calls ring inside the app or forward to a real phone, and what the caller sees while connecting. It is a company-level configuration — saving updates the company record, not the individual user — and is organized as "during work hours," "after hours," and "customization."
What it does
- Chooses who answers first during working hours: AI-then-human, human direct, or AI-only.
- Chooses where human calls land: in the dashboard/mobile app, forward-after-30s, or forward-all-instantly (with a forwarding phone number).
- Shows the after-hours behavior (AI handles, or voicemail if AI is off) — informational, derived from whether AI calling is enabled.
- Customizes the caller screen: optionally ask the visitor for a phone number before connecting, and pick a background image or color.
- Renders a live Call Flow Preview (sticky on desktop, summary card on mobile) reflecting the current selection.
How it works
The form (calls/Preferences.vue) is a vee-validate + zod form whose UI fields map onto a mix of modern (ai_config.call_routing) and legacy company fields. On Save Changes it PUTs the company.
Step 1 — Who answers first (during work hours)
Maps to company.ai_config.call_routing:
| UI option | call_routing value | Flow |
|---|---|---|
| AI greets first, then transfers to me | ai_to_human | Visitor → AI greets & qualifies → transfer to you |
| Calls come directly to me | human | Visitor → direct to you (no AI greeting) |
| Let AI handle everything | ai | Visitor → AI agent → resolved |
The two AI options are disabled unless AI calling is enabled (company.ai_calling.enable); they show "(AI not enabled)". Backend default for call_routing is ai_to_human. If AI is disabled but a saved value was an AI option, the form falls back to displaying human.
Step 2 — Where to take calls (only when a human is involved)
Shown only for human or ai_to_human. Maps to legacy company flags:
| UI option | allow_twilio_calls | always_twilio_calls | Behavior |
|---|---|---|---|
Answer on Dashboard or Mobile App (receive) | false | false | Rings inside Knock Knock. |
Forward to phone if I don't answer (forward-missed) | true | false | Rings the dashboard first, forwards after 30 seconds. |
Forward all calls instantly (forward-all) | true | true | Goes straight to your phone/landline. |
Both forward options require a forwarding phone number (forwardPhoneNumber, saved to company.phone_number); the field is required by validation when forwarding is selected.
After hours
Not a control — an informational card. When AI calling is enabled it states AI handles all calls when you're offline; otherwise it states calls go to voicemail (AI not enabled). The actual "online vs offline" boundary comes from Working Hours.
Caller screen (collapsible "Caller Screen Settings")
| Setting | Field | Notes |
|---|---|---|
| Ask for phone number before connecting | take_phone_number_before_call | Backend default true. |
| Call screen background (image) | widget_design.call_background.background_image | Choices fetched from GET /default-call-backgrounds. |
| Call screen background (color) | widget_design.call_background.background_color | Presets #404040, #163236, #1e3a5f, #4c1d95, or a custom color picker. Default #404040. |
Selecting an image clears the color and vice versa. A small phone-shaped preview reflects the choice.
Configuration & options
Full field map written by Save Changes (PUT /company/<id>):
| UI control | Payload field(s) |
|---|---|
| Who answers first | ai_config.call_routing (ai_to_human | human | ai) |
| Where to take calls | allow_twilio_calls, always_twilio_calls |
| Forwarding number | phone_number |
| Ask for phone number | take_phone_number_before_call |
| Background image | widget_design.call_background.background_image |
| Background color | widget_design.call_background.background_color (defaults to #404040) |
For QA/support, the round-trip mapping when reading company data back into the form (initializeForm):
allow_twilio_calls && always_twilio_calls→forward-allallow_twilio_callsonly →forward-missed- neither →
receive
Behaviors & edge cases
- Company-scoped, not per-user: this screen changes the whole company's call handling. Distinct from the user's personal Working Hours.
- AI options gated: with
ai_calling.enable === false, the AI handler tiles are disabled and a saved AI value is coerced tohumanin the form. - Forwarding requires a number: validation blocks save if
forward-missed/forward-allis chosen with an empty forwarding number. - 30-second forward is fixed copy in the UI for
forward-missed; the actual delay is enforced server-side in the call/Twilio flow (verify the exact timeout value in the call service). - Image vs color are mutually exclusive on the caller screen.
- Unsaved-changes guard: leaving with a dirty form prompts to save (
onBeforeRouteLeave+swal). - Legacy fields:
allow_twilio_calls/always_twilio_callsare legacy flags the frontend still drives; the newer routing concept lives underai_config.call_routing. Both are written on save.
Plan & limits
Available on all plans behind the settings.calls permission. The AI-greeting and AI-only routing options additionally require AI calling to be enabled for the company (ai_calling.enable) — a per-account/plan capability. Forwarding relies on the telephony (Twilio) integration. Whether AI calling and forwarding are bundled or add-ons is verify with product/pricing.
Technical implementation
- View:
frontend/src/views/settings/calls/Preferences.vue(vee-validate + zod) - Route: name
settings-calls-preferences, path/settings/calls/preferences, meta{ permission: 'settings.calls' }(frontend/src/router/index.js) - Reads:
company.ai_config.call_routing,company.ai_calling.enable,company.allow_twilio_calls,company.always_twilio_calls,company.phone_number,company.take_phone_number_before_call,company.widget_design.call_background.* - Writes:
PUT /company/<id>with the fields above; backgrounds list fromGET /default-call-backgrounds - Model fields:
CompanyModel(take_phone_number_before_call,widget_design.call_background,ai_config, twilio flags) - See Calls for the runtime call experience, and services/ms-communication for telephony.
Related
- Settings — Working Hours — defines online vs after-hours, which this screen's "After Hours" card depends on.
- Calls — the actual call/answer experience and missed-call handling.
- Widget — Styles & Appearance — the broader
widget_designthe caller background lives under. - services/ms-communication — call routing/telephony runtime.