Skip to main content

Settings — Call Preferences

Audience: Sales · Support · QA · Management · Engineering · Where in app: main sidebar Website Widget → Call Settings (/settings/calls/preferences; mainNav group website-widget in useSettingsMenu.js since b57d923c — no longer in the Settings panel except inside the agency setup frame) · 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 optioncall_routing valueFlow
AI greets first, then transfers to meai_to_humanVisitor → AI greets & qualifies → transfer to you
Calls come directly to mehumanVisitor → direct to you (no AI greeting)
Let AI handle everythingaiVisitor → 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 optionallow_twilio_callsalways_twilio_callsBehavior
Answer on Dashboard or Mobile App (receive)falsefalseRings inside Knock Knock.
Forward to phone if I don't answer (forward-missed)truefalseRings the dashboard first, forwards after 30 seconds.
Forward all calls instantly (forward-all)truetrueGoes 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.

Below the three tiles, the Audio call on phone toggle (allowAudioToPhone → company.allow_audio_to_phone, default false) forwards widget audio calls (only) to the forwarding number — the visitor's browser dials it through the widget's Twilio Voice device (see Calls › Visitor phone-call token); video calls still ring in the dashboard. It also needs the forwarding number (Forward to).

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")​

SettingFieldNotes
Ask for phone number before connectingtake_phone_number_before_callBackend default true.
Call screen background (image)widget_design.call_background.background_imageChoices fetched from GET /default-call-backgrounds.
Call screen background (color)widget_design.call_background.background_colorPresets #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 controlPayload field(s)
Who answers firstai_config.call_routing (ai_to_human | human | ai)
Where to take callsallow_twilio_calls, always_twilio_calls
Forwarding numberphone_number
Audio call on phoneallow_audio_to_phone
Ask for phone numbertake_phone_number_before_call
Background imagewidget_design.call_background.background_image
Background colorwidget_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-all
  • allow_twilio_calls only → 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 to human in the form.
  • Forwarding requires a number — only while a human is involved (05fc6280, 2026-10-13): the number is required when callHandler is human/ai_to_human and forward-missed/forward-all or allowAudioToPhone is set. Before the fix a stale forwarding preference made the hidden field required after switching to ai, and Save failed silently. Validation errors (onInvalidSubmit) and server errors now raise a toast — the ErrorAlert sits at the top of the page, usually scrolled out of view. A missing widget_design no longer crashes the payload build.
  • 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_calls are legacy flags the frontend still drives; the newer routing concept lives under ai_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 from GET /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.